# Stripe

> Payments platform. Retrieve invoices and invoice line items, and receive webhook events for charges, payment intents, customers, invoices, and checkout sessions.

Source: https://cotera.co/docs/reference/tools/individual-tools/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](https://docs.stripe.com/keys) 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](https://cotera.co/docs/reference/webhooks/stripe.md), 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](#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](#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](https://docs.stripe.com/api/invoices/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](#list-invoice-line-items) to page through the rest.

**Example Usage:**

```json
{
  "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:**

```json
{
  "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](https://cotera.co/docs/reference/webhooks/stripe.md), 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](https://cotera.co/docs/reference/tools/individual-tools/orb.md#mark-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