cotera
Logo

Stripe

Authentication Type: API Key
Description: Payments platform. Retrieve invoices and invoice line items, and receive webhook events for charges, payment intents, customers, invoices, and checkout sessions.

Authentication

To authenticate with Stripe, you'll need a Stripe API key. We recommend a restricted API key scoped to only what these tools need, rather than your full secret key.

You'll need to provide:

  • apiKey string: Your Stripe secret or restricted API key, sent as a Bearer token on every request.

Required Permissions:

  • Billing → Invoices: Read (invoice_read) - Retrieve invoices and their line items

Test-mode keys only see test-mode invoices, and live-mode keys only see live-mode invoices.

The same Stripe connection is used by the Stripe webhook trigger, which creates webhook endpoints on your behalf. If you use both, the key needs permission for that as well.

Security tip: Do not commit your Stripe API key to version control or share it in public channels. Roll it immediately if it is ever exposed.

Invoices

Retrieve Stripe invoices and their line items.

Both tools use Stripe's own field names, so a result lines up field-for-field with the invoice.paid webhook payload and the Stripe API reference:

  • Amounts are integers in the currency's smallest unit (e.g. cents — 12500 is $125.00).
  • Timestamps are Unix seconds.
  • Expanded objects are reduced to their IDs. Fields such as customer, discounts, and default_payment_method are always returned as IDs.
  • Fields that don't apply to an invoice are returned as null.

Get Invoice

Retrieve a Stripe invoice by ID. Returns the full invoice object, including the first page of its line items in lines.

Operation Type: Query (Read)

Parameters:

  • invoice_id string (required): ID of the Stripe invoice to retrieve (e.g. in_1MtHbELkdIwHu7ixl4OzzPMv)

Returns:

  • id string: Invoice ID (in_...)
  • object string: Always invoice
  • number string (nullable): Human-readable invoice number
  • status string (nullable): draft, open, paid, uncollectible, or void
  • billing_reason string (nullable): Why the invoice was created (e.g. manual, subscription_cycle, subscription_create)
  • collection_method string (nullable): charge_automatically or send_invoice
  • currency string (nullable): Three-letter ISO currency code, lowercase
  • amount_due number (nullable): Final amount due at this time
  • amount_paid number (nullable): Amount that was paid
  • amount_remaining number (nullable): Difference between amount_due and amount_paid
  • amount_overpaid number (nullable): Amount paid beyond the amount due
  • amount_shipping number (nullable): Shipping cost included in the invoice
  • subtotal number (nullable): Total before discounts and taxes
  • subtotal_excluding_tax number (nullable): Subtotal excluding inclusive taxes
  • total number (nullable): Total after discounts and taxes
  • total_excluding_tax number (nullable): Total excluding inclusive taxes
  • starting_balance number (nullable): Customer balance before the invoice was finalized
  • ending_balance number (nullable): Customer balance after the invoice was finalized
  • customer string (nullable): ID of the customer who will be billed (cus_...)
  • customer_email string (nullable): Customer's email at finalization
  • customer_name string (nullable): Customer's name at finalization
  • customer_phone string (nullable): Customer's phone number at finalization
  • customer_address object (nullable): Customer's address at finalization
  • customer_shipping object (nullable): Customer's shipping information at finalization
  • customer_tax_exempt string (nullable): exempt, none, or reverse
  • customer_tax_ids array (nullable): Customer's tax IDs at finalization
  • description string (nullable): Arbitrary description (the invoice memo)
  • footer string (nullable): Footer displayed on the invoice
  • metadata object: Key/value pairs attached to the invoice
  • hosted_invoice_url string (nullable): URL of the hosted invoice page
  • invoice_pdf string (nullable): Link to download the invoice PDF
  • created number (nullable): Creation time (Unix seconds)
  • due_date number (nullable): Date on which payment is due (Unix seconds)
  • effective_at number (nullable): Date the invoice is considered in effect (Unix seconds)
  • period_start number (nullable): Start of the usage period (Unix seconds)
  • period_end number (nullable): End of the usage period (Unix seconds)
  • status_transitions object (nullable): Timestamps of status changes
    • finalized_at number (nullable): When the invoice was finalized (Unix seconds)
    • paid_at number (nullable): When the invoice was paid (Unix seconds)
    • marked_uncollectible_at number (nullable): When the invoice was marked uncollectible (Unix seconds)
    • voided_at number (nullable): When the invoice was voided (Unix seconds)
  • attempted boolean (nullable): Whether an attempt has been made to pay the invoice
  • attempt_count number (nullable): Number of payment attempts made for this invoice
  • next_payment_attempt number (nullable): Next automatic payment attempt (Unix seconds)
  • auto_advance boolean (nullable): Whether Stripe performs automatic collection
  • automatically_finalizes_at number (nullable): When a draft invoice will be automatically finalized (Unix seconds)
  • lines object: The first page of line items. Use List Invoice Line Items for the rest.
    • object string: Always list
    • data array of objects: Line items on this page, with the same fields as List Invoice Line Items
    • has_more boolean: Whether more line items exist after this page
    • total_count number (nullable): Total number of line items, when Stripe reports it
    • url string: API URL for the full list
  • discounts array of strings: IDs of the discounts applied to the invoice
  • parent object (nullable): What generated the invoice: type plus subscription_details (subscription, metadata) or quote_details
  • default_payment_method string (nullable): ID of the default payment method
  • default_source string (nullable): ID of the default payment source
  • livemode boolean (nullable): true in live mode, false in test mode

The invoice also includes Stripe's remaining invoice fields, unchanged: account_country, account_name, account_tax_ids, application, automatic_tax, custom_fields, customer_account, default_tax_rates, from_invoice, issuer, last_finalization_error, latest_revision, on_behalf_of, payment_settings, post_payment_credit_notes_amount, pre_payment_credit_notes_amount, receipt_number, rendering, shipping_cost, shipping_details, statement_descriptor, status_details, test_clock, threshold_reason, total_discount_amounts, total_pretax_credit_amounts, total_taxes, and webhooks_delivered_at. See Stripe's invoice object reference for their shape.

Behavior notes:

  • lines holds only the first page of line items. When lines.has_more is true, call List Invoice Line Items to page through the rest.

Example Usage:

{
  "invoice_id": "in_1MtHbELkdIwHu7ixl4OzzPMv"
}

List Invoice Line Items

Retrieve a Stripe invoice's line items, one page at a time.

Operation Type: Query (Read)

Parameters:

  • invoice_id string (required): ID of the Stripe invoice whose line items to list (e.g. in_1MtHbELkdIwHu7ixl4OzzPMv)
  • limit number (nullable): Number of line items to return, between 1 and 100. null uses Stripe's default of 10.
  • starting_after string (nullable): Pagination cursor — a line item ID. Returns the page after it. Pass the id of the last item from the previous page.
  • ending_before string (nullable): Pagination cursor — a line item ID. Returns the page before it. Pass the id of the first item from the current page.

Returns:

  • object string: Always list
  • data array of objects: Line items on this page
    • id string: Line item ID (il_...)
    • object string: Always line_item
    • invoice string (nullable): ID of the invoice that contains this line item
    • description string (nullable): Description of the line item
    • amount number (nullable): Amount in the currency's smallest unit, including discounts and excluding tax
    • subtotal number (nullable): Amount before discounts and taxes
    • currency string (nullable): Three-letter ISO currency code, lowercase
    • quantity number (nullable): Quantity of the subscription or invoice item
    • quantity_decimal string (nullable): Quantity as a decimal string
    • period object (nullable): Service period covered by this line item
      • start number (nullable): Start of the service period (Unix seconds)
      • end number (nullable): End of the service period (Unix seconds)
    • pricing object (nullable): How the line item was priced: price_details (price, product), type, unit_amount_decimal
    • parent object (nullable): What generated the line item: type is invoice_item_details or subscription_item_details, with the matching details object
    • discountable boolean (nullable): Whether discounts can apply to this line item
    • discounts array of strings: IDs of the discounts applicable to this line item
    • discount_amounts array (nullable): Amount of each discount applied to this line item
    • pretax_credit_amounts array (nullable): Pre-tax credits applied to this line item
    • taxes array (nullable): Taxes applied to this line item
    • metadata object: Key/value pairs attached to the line item
    • livemode boolean (nullable): true in live mode, false in test mode
  • has_more boolean: Whether more line items exist after this page
  • total_count number (nullable): Total number of line items, when Stripe reports it
  • url string: API URL for the full list

Behavior notes:

  • limit is clamped to 1–100: values below 1 become 1 and values above 100 become 100.
  • To page forward, call again with starting_after set to the id of the last item in data, and repeat until has_more is false.
  • To page backward, set ending_before to the id of the first item in data.

Example Usage:

{
  "invoice_id": "in_1MtHbELkdIwHu7ixl4OzzPMv",
  "limit": 100,
  "starting_after": "il_1MtHbELkdIwHu7ixKfDkzGS2"
}

Common Use Cases

Reconciling Stripe payments into your billing system:

  • Trigger a workflow on the Stripe invoice.paid webhook, read the Orb invoice ID from the Stripe invoice's metadata (Orb's Stripe Invoice Sync writes orb_invoice_id, orb_customer_id, and related keys), then mark the Orb invoice as paid
  • Convert status_transitions.paid_at from Unix seconds to a YYYY-MM-DD date before passing it on as the payment date

Answering billing questions:

  • Retrieve an invoice to see what a customer owes, what they've paid, and when it's due
  • Share hosted_invoice_url or invoice_pdf with the customer or an internal team

Auditing what was charged:

  • Page through an invoice's line items to break a total down by product, quantity, and service period