<!-- Generated by `just docs` from catalog/toolkits/stripe.yaml, catalog/expansions/stripe.yaml, catalog/evals/scorecard.json. Edit the source, not this file. -->

# Stripe

Payments and billing. Manage customers, collect and refund payments, issue invoices, and run recurring subscriptions.

| Property | Value |
| --- | --- |
| Slug | `stripe` |
| Definition version | `0.1.0` |
| Base URL | `https://api.stripe.com/v1` |
| Auth schemes | `api_key` |
| Action tools | 31 |
| By class | 13 read, 12 write, 6 destructive |
| Triggers | 0 |
| Provider rate limit | 100 requests per 1s, per account |

## Measured routing accuracy

46 golden cases replayed through the router over the whole index: measured over corpus `ea4f12ad2948` (65 toolkits, 2283 tools indexed and 13 declared uncallable), 31 cases written by hand and 15 cases from the paraphrase pass. A case counts as top-1 when its gold tool ranked first and top-8 when it reached the slate at all.

| Measure | Cases | Share |
| --- | --- | --- |
| top-1 | 29/46 | 63.0% |
| top-8 | 40/46 | 87.0% |

The sweep is offline: the reranker is a deterministic identity fake that returns candidates in the order retrieval produced them, so top-1 measures retrieval order rather than a reranked slate. `just eval-live` measures the same cases through the live reranker.

## Authentication

Connect an entity with `ConnectionsService.InitiateConnection`, naming this toolkit's slug. Credentials stay in the connections vault; callers hold connected-account ids only.

### `api_key`

| Property | Value |
| --- | --- |
| Placement | `header` |
| Name | `Authorization` |
| Rendered as | `Bearer {key}` |

Submit the key with `ConnectionsService` rather than putting it in a request; it is sealed at rest and never returned.

## Tools

31 action tools. The catalog-wide slug is `stripe.<tool>`, which is what `search_tools` returns and `call_tool` takes.

### `stripe.create_customer`

Create a new customer record for billing. Use when the user wants to add, register, or set up a new customer, buyer, or account before charging them or starting a subscription. Optional name, email, and phone.

Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `POST /customers`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `description` | string | no | Internal note about this customer, not shown to them. |
| `email` | string | no | Customer's email address, e.g. "jane@example.com". |
| `metadata` | object | no | Optional key-value metadata to attach, e.g. {"account_id": "6735"}. |
| `name` | string | no | Customer's full name or business name. |
| `phone` | string | no | Customer's phone number. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `balance` | integer |  |
| `created` | integer |  |
| `currency` | string |  |
| `email` | string |  |
| `id` | string |  |
| `name` | string |  |
| `phone` | string |  |

Also retrieved by: "set up a new buyer in stripe", "I need a billing profile for this client", "register this person so we can charge them later", "add someone to our customer list", "onboard a new account for payments".

### `stripe.get_customer`

Get one customer's details by their Stripe customer id: name, email, phone, and account balance. Use when the user names a specific customer. For finding customers by email or browsing all of them, use list_customers.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /customers/{{params.customer_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `customer_id` | string | **yes** | Stripe customer id, e.g. "cus_Qx7Nk2VbA1u9Zp". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `balance` | integer |  |
| `created` | integer |  |
| `currency` | string |  |
| `delinquent` | boolean |  |
| `email` | string |  |
| `id` | string |  |
| `name` | string |  |
| `phone` | string |  |

Also retrieved by: "pull up this person's billing profile", "what's on file for this buyer", "check their account balance", "look up their contact info in stripe".

### `stripe.list_customers`

List customers on the account, optionally filtered by email. Use when the user asks who our customers are, wants to look someone up by email, or browses the customer base. For one known customer, use get_customer.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /customers`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `email` | string | no | Only customers with this exact email address. |
| `limit` | integer | no | Results per page, max 100. Defaults to 10. |
| `starting_after` | string | no | Customer id to page after, from a previous page's last result. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `data` | array of object |  |
| `data[].created` | integer |  |
| `data[].email` | string |  |
| `data[].id` | string |  |
| `data[].name` | string |  |
| `has_more` | boolean |  |

Also retrieved by: "who's on our books", "find the buyer with this email", "show everyone we bill", "search for a customer by their email address".

### `stripe.update_customer`

Edit an existing customer's name, email, phone, or description. Use when the user wants to update, correct, or change a customer's contact details. Only the fields given change; omit others to leave them as is.

Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `POST /customers/{{params.customer_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `customer_id` | string | **yes** | Stripe customer id to update. |
| `description` | string | no | New internal note about this customer. |
| `email` | string | no | New email address. |
| `name` | string | no | New name. |
| `phone` | string | no | New phone number. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `email` | string |  |
| `id` | string |  |
| `name` | string |  |
| `phone` | string |  |

Also retrieved by: "fix their email on file", "this person's phone number changed", "correct the billing contact details", "change what we have saved for them".

### `stripe.delete_customer`

Permanently delete a customer and detach their payment methods. Irreversible; open invoices and subscriptions are not canceled first. Use only when the user explicitly asks to delete or remove a customer record entirely.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). No scopes beyond the connection's defaults. Calls `DELETE /customers/{{params.customer_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `customer_id` | string | **yes** | Stripe customer id to delete. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `deleted` | boolean |  |
| `id` | string |  |

Also retrieved by: "wipe this buyer out of stripe for good", "get rid of their billing profile entirely", "remove them from our records completely", "erase this account, they asked to be forgotten".

### `stripe.create_payment_intent`

Start a payment intent to collect a charge from a customer for a given amount and currency. Use when the user wants to charge a card, collect payment, or bill someone once. Confirm separately with confirm_payment_intent.

Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `POST /payment_intents`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `amount` | integer | **yes** | Amount in the smallest currency unit, e.g. 2000 for $20.00 usd. |
| `currency` | string | **yes** | Three-letter ISO currency code, e.g. "usd". |
| `customer` | string | no | Stripe customer id to charge. |
| `description` | string | no | Internal note about this charge. |
| `metadata` | object | no | Optional key-value metadata to attach, e.g. {"order_id": "6735"}. |
| `payment_method` | string | no | Stripe payment method id to attach, e.g. "pm_1NakL2". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `amount` | integer |  |
| `client_secret` | string |  |
| `currency` | string |  |
| `customer` | string |  |
| `id` | string |  |
| `status` | string |  |

Also retrieved by: "charge this card for the order", "bill them for what they owe", "take payment for this purchase", "set up a one-time charge", "collect money from this buyer".

### `stripe.get_payment_intent`

Get one payment intent by id: its status, amount, currency, and linked customer. Use when the user asks whether a charge went through or wants details on a specific payment attempt.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /payment_intents/{{params.payment_intent_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `payment_intent_id` | string | **yes** | Stripe payment intent id, e.g. "pi_3P9k2VbA1u9Zp". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `amount` | integer |  |
| `created` | integer |  |
| `currency` | string |  |
| `customer` | string |  |
| `description` | string |  |
| `id` | string |  |
| `status` | string |  |

Also retrieved by: "did that charge go through", "check the status of this payment attempt", "what happened with this transaction".

### `stripe.list_payment_intents`

List payment intents, optionally filtered by customer. Use when the user asks about recent charges, payment attempts, or a customer's payment history. For a single known payment, use get_payment_intent.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /payment_intents`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `customer` | string | no | Only payment intents for this customer id. |
| `limit` | integer | no | Results per page, max 100. Defaults to 10. |
| `starting_after` | string | no | Payment intent id to page after, from a previous page's last result. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `data` | array of object |  |
| `data[].amount` | integer |  |
| `data[].currency` | string |  |
| `data[].customer` | string |  |
| `data[].id` | string |  |
| `data[].status` | string |  |
| `has_more` | boolean |  |

Also retrieved by: "show this buyer's payment history", "what charges have we tried recently", "pull up recent transactions for this account".

### `stripe.confirm_payment_intent`

Confirm a payment intent with a payment method to actually attempt the charge. Use when the user wants to complete, finalize, or run a payment that was started but not yet charged.

Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `POST /payment_intents/{{params.payment_intent_id}}/confirm`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `payment_intent_id` | string | **yes** | Stripe payment intent id to confirm. |
| `payment_method` | string | no | Payment method id to charge, if not already attached. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `client_secret` | string |  |
| `id` | string |  |
| `status` | string |  |

Also retrieved by: "run the charge now that we have a card", "go ahead and process that payment", "finish collecting on this pending charge".

### `stripe.capture_payment_intent`

Capture funds on a payment intent that was authorized but held, completing the charge. Use when the user wants to capture, collect, or finalize an authorized hold, e.g. after shipping an order. Supports a partial capture amount.

Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `POST /payment_intents/{{params.payment_intent_id}}/capture`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `amount_to_capture` | integer | no | Amount to capture in the smallest currency unit. Defaults to the full authorized amount. |
| `payment_intent_id` | string | **yes** | Stripe payment intent id to capture. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `amount_received` | integer |  |
| `id` | string |  |
| `status` | string |  |

Also retrieved by: "grab the funds we held on their card", "collect the hold now that we shipped", "finalize the authorized charge".

### `stripe.cancel_payment_intent`

Cancel a payment intent before it is captured, releasing any authorization hold. Irreversible once canceled; a new payment intent is needed to charge later. Use when the user wants to abandon, drop, or call off a pending charge.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). No scopes beyond the connection's defaults. Calls `POST /payment_intents/{{params.payment_intent_id}}/cancel`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `cancellation_reason` | string, one of duplicate, fraudulent, requested_by_customer, abandoned | no | Why the payment intent is being canceled. |
| `payment_intent_id` | string | **yes** | Stripe payment intent id to cancel. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `cancellation_reason` | string |  |
| `id` | string |  |
| `status` | string |  |

Also retrieved by: "drop this pending charge before it goes through", "release the hold on their card", "never mind, don't charge them after all", "abandon this payment attempt".

### `stripe.get_charge`

Get one charge by id: amount, status, whether it was refunded, and the customer and payment intent it belongs to. Use when the user names a specific charge id. For refund details, use get_refund.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /charges/{{params.charge_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `charge_id` | string | **yes** | Stripe charge id, e.g. "ch_3P9k2VbA1u9Zp". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `amount` | integer |  |
| `created` | integer |  |
| `currency` | string |  |
| `customer` | string |  |
| `id` | string |  |
| `paid` | boolean |  |
| `payment_intent` | string |  |
| `refunded` | boolean |  |
| `status` | string |  |

Also retrieved by: "look up this specific transaction", "pull details on a past charge", "was this charge ever refunded".

### `stripe.list_charges`

List charges, optionally filtered by customer or payment intent. Use when the user asks for a customer's charge history or past transactions. For refund status specifically, use list_refunds.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /charges`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `customer` | string | no | Only charges for this customer id. |
| `limit` | integer | no | Results per page, max 100. Defaults to 10. |
| `payment_intent` | string | no | Only the charge belonging to this payment intent id. |
| `starting_after` | string | no | Charge id to page after, from a previous page's last result. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `data` | array of object |  |
| `data[].amount` | integer |  |
| `data[].currency` | string |  |
| `data[].customer` | string |  |
| `data[].id` | string |  |
| `data[].refunded` | boolean |  |
| `data[].status` | string |  |
| `has_more` | boolean |  |

Also retrieved by: "show past transactions for this buyer", "what have we charged them so far", "pull their transaction history".

### `stripe.create_refund`

Refund a charge or payment intent, in full or in part. Irreversible once processed; the funds return to the customer's original payment method. Use when the user wants to refund, reverse, or give money back for a charge.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). No scopes beyond the connection's defaults. Calls `POST /refunds`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `amount` | integer | no | Amount to refund in the smallest currency unit. Omit to refund in full. |
| `charge` | string | no | Stripe charge id to refund. Give this or payment_intent. |
| `payment_intent` | string | no | Stripe payment intent id to refund. Give this or charge. |
| `reason` | string, one of duplicate, fraudulent, requested_by_customer | no | Why the refund is being issued. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `amount` | integer |  |
| `currency` | string |  |
| `id` | string |  |
| `payment_intent` | string |  |
| `reason` | string |  |
| `status` | string |  |

Also retrieved by: "give this customer their money back", "reverse that charge, they want out", "send back what we took by mistake", "process a refund for a bad order", "undo this transaction and return the funds".

### `stripe.get_refund`

Get one refund by id: its status, amount, and the charge or payment intent it applies to. Use when the user asks whether a specific refund went through.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /refunds/{{params.refund_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `refund_id` | string | **yes** | Stripe refund id, e.g. "re_3P9k2VbA1u9Zp". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `amount` | integer |  |
| `created` | integer |  |
| `currency` | string |  |
| `id` | string |  |
| `payment_intent` | string |  |
| `reason` | string |  |
| `status` | string |  |

Also retrieved by: "did their money actually go back", "check on the status of a refund", "confirm this refund cleared".

### `stripe.list_refunds`

List refunds, optionally filtered by payment intent or charge. Use when the user asks what has been refunded or wants a refund history for a customer or charge.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /refunds`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `charge` | string | no | Only refunds against this charge id. |
| `limit` | integer | no | Results per page, max 100. Defaults to 10. |
| `payment_intent` | string | no | Only refunds against this payment intent id. |
| `starting_after` | string | no | Refund id to page after, from a previous page's last result. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `data` | array of object |  |
| `data[].amount` | integer |  |
| `data[].currency` | string |  |
| `data[].id` | string |  |
| `data[].payment_intent` | string |  |
| `data[].status` | string |  |
| `has_more` | boolean |  |

Also retrieved by: "what have we refunded lately", "show refund history for this charge", "pull up everything we've given back".

### `stripe.create_invoice`

Create a draft invoice for a customer, to be filled with invoice items before finalizing. Use when the user wants to start, draft, or open a new invoice or bill. Add line items with create_invoice_item, then finalize_invoice.

Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `POST /invoices`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `collection_method` | string, one of charge_automatically, send_invoice | no | How payment is collected. Defaults to charge_automatically. |
| `customer` | string | **yes** | Stripe customer id to bill. |
| `description` | string | no | Text shown on the invoice, e.g. "June consulting hours". |
| `due_date` | integer | no | Unix timestamp payment is due by. Required when collection_method is send_invoice. |
| `metadata` | object | no | Optional key-value metadata to attach, e.g. {"po_number": "4471"}. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `amount_due` | integer |  |
| `currency` | string |  |
| `customer` | string |  |
| `hosted_invoice_url` | string |  |
| `id` | string |  |
| `status` | string |  |

Also retrieved by: "start a bill for this client", "draft up an invoice", "open a new bill I can add items to", "kick off billing for this account".

### `stripe.get_invoice`

Get one invoice by id: its status, amount due, amount paid, due date, and hosted payment page url. Use when the user names a specific invoice.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /invoices/{{params.invoice_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `invoice_id` | string | **yes** | Stripe invoice id, e.g. "in_1P9k2VbA1u9Zp". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `amount_due` | integer |  |
| `amount_paid` | integer |  |
| `currency` | string |  |
| `customer` | string |  |
| `due_date` | integer |  |
| `hosted_invoice_url` | string |  |
| `id` | string |  |
| `number` | string |  |
| `status` | string |  |

Also retrieved by: "pull up this specific bill", "check the status on an invoice", "how much do they still owe on this".

### `stripe.list_invoices`

List invoices, optionally filtered by customer or status such as draft, open, or paid. Use when the user asks about a customer's invoices, unpaid bills, or billing history.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /invoices`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `customer` | string | no | Only invoices for this customer id. |
| `limit` | integer | no | Results per page, max 100. Defaults to 10. |
| `starting_after` | string | no | Invoice id to page after, from a previous page's last result. |
| `status` | string, one of draft, open, paid, uncollectible, void | no | Only invoices in this state. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `data` | array of object |  |
| `data[].amount_due` | integer |  |
| `data[].currency` | string |  |
| `data[].customer` | string |  |
| `data[].id` | string |  |
| `data[].status` | string |  |
| `has_more` | boolean |  |

Also retrieved by: "show this customer's unpaid bills", "what invoices are outstanding", "pull their billing history".

### `stripe.finalize_invoice`

Finalize a draft invoice, locking its line items and generating the invoice number and payment page. Use when the user wants to lock in, close out, or ready a draft invoice for payment or sending.

Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `POST /invoices/{{params.invoice_id}}/finalize`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `auto_advance` | boolean | no | True to let Stripe automatically attempt collection after finalizing. |
| `invoice_id` | string | **yes** | Stripe draft invoice id to finalize. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `hosted_invoice_url` | string |  |
| `id` | string |  |
| `number` | string |  |
| `status` | string |  |

Also retrieved by: "lock this draft bill so it's ready to send", "close out the invoice details", "make this invoice official".

### `stripe.send_invoice`

Email a finalized invoice to the customer for payment. Use when the user wants to send, deliver, or mail an invoice to whoever owes it. The invoice must already be finalized.

Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `POST /invoices/{{params.invoice_id}}/send`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `invoice_id` | string | **yes** | Stripe finalized invoice id to email. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string |  |
| `status` | string |  |

Also retrieved by: "email them the bill", "get this invoice out to the customer", "deliver the invoice so they can pay".

### `stripe.pay_invoice`

Attempt to collect payment on an open invoice right away, charging the customer's default payment method. Use when the user wants to collect, charge, or force payment on a bill now rather than waiting.

Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `POST /invoices/{{params.invoice_id}}/pay`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `invoice_id` | string | **yes** | Stripe open invoice id to pay. |
| `paid_out_of_band` | boolean | no | True to mark the invoice paid without charging anything, e.g. a wire received outside Stripe. |
| `payment_method` | string | no | Payment method id to charge instead of the customer's default. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `amount_paid` | integer |  |
| `id` | string |  |
| `status` | string |  |

Also retrieved by: "charge them for this bill right now", "force collection on an open invoice", "go ahead and collect on this now instead of waiting".

### `stripe.void_invoice`

Void a finalized invoice that will never be paid. Irreversible; the invoice stays on record marked void instead of being deleted. Use when the user wants to cancel, kill, or invalidate an invoice that was sent by mistake.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). No scopes beyond the connection's defaults. Calls `POST /invoices/{{params.invoice_id}}/void`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `invoice_id` | string | **yes** | Stripe finalized invoice id to void. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string |  |
| `status` | string |  |

Also retrieved by: "kill this invoice, we sent it by mistake", "cancel a bill that should never be paid", "invalidate this invoice permanently".

### `stripe.delete_invoice`

Permanently delete a draft invoice that has not been finalized. Irreversible and only works while the invoice is still a draft. For a finalized invoice that should never be paid, use void_invoice instead.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). No scopes beyond the connection's defaults. Calls `DELETE /invoices/{{params.invoice_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `invoice_id` | string | **yes** | Stripe draft invoice id to delete. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `deleted` | boolean |  |
| `id` | string |  |

Also retrieved by: "scrap this draft bill, never mind", "throw out an invoice we haven't sent yet", "get rid of this unfinished bill".

### `stripe.create_invoice_item`

Add a line item, charge, or credit to a customer's next invoice, or to a specific draft invoice. Use when the user wants to add a charge, fee, or product line to a bill before it is finalized.

Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `POST /invoiceitems`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `amount` | integer | **yes** | Amount in the smallest currency unit. Negative for a credit. |
| `currency` | string | **yes** | Three-letter ISO currency code, e.g. "usd". |
| `customer` | string | **yes** | Stripe customer id this line item bills. |
| `description` | string | no | Text shown on the invoice for this line item. |
| `invoice` | string | no | Draft invoice id to attach to. Omit to queue for the customer's next invoice. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `amount` | integer |  |
| `currency` | string |  |
| `customer` | string |  |
| `description` | string |  |
| `id` | string |  |
| `invoice` | string |  |

Also retrieved by: "add a fee to their next bill", "tack on a charge before this invoice goes out", "queue up a line item for the next billing cycle", "credit them something on their upcoming invoice".

### `stripe.list_invoice_items`

List pending invoice items for a customer or invoice that have not yet been billed. Use when the user asks what charges are queued up for someone's next invoice.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /invoiceitems`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `customer` | string | no | Only line items for this customer id. |
| `invoice` | string | no | Only line items attached to this draft invoice id. |
| `limit` | integer | no | Results per page, max 100. Defaults to 10. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `data` | array of object |  |
| `data[].amount` | integer |  |
| `data[].currency` | string |  |
| `data[].customer` | string |  |
| `data[].description` | string |  |
| `data[].id` | string |  |
| `has_more` | boolean |  |

Also retrieved by: "what's queued up for their next bill", "show pending charges not yet invoiced", "see what's waiting to be billed".

### `stripe.create_subscription`

Start a recurring subscription for a customer on one or more prices. Use when the user wants to subscribe, sign up, or put a customer on a recurring plan. Supports a trial period before the first charge.

Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `POST /subscriptions`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `collection_method` | string, one of charge_automatically, send_invoice | no | How each billing period is collected. Defaults to charge_automatically. |
| `customer` | string | **yes** | Stripe customer id to subscribe. |
| `items` | array of object | **yes** | Price and quantity pairs the subscription bills for. |
| `items[].price` | string | **yes** | Stripe price id, e.g. "price_1P9k2VbA1u9Zp". |
| `items[].quantity` | integer | no | Quantity of this price. Defaults to 1. |
| `metadata` | object | no | Optional key-value metadata to attach, e.g. {"plan_source": "referral"}. |
| `trial_period_days` | integer | no | Days of free trial before the first charge. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `current_period_end` | integer |  |
| `customer` | string |  |
| `id` | string |  |
| `items` | array of object |  |
| `items[].id` | string |  |
| `items[].price` | object |  |
| `items[].price.id` | string |  |
| `status` | string |  |

Also retrieved by: "put this customer on a recurring plan", "sign them up for our monthly service", "start billing them every cycle", "set up a subscription with a free trial".

### `stripe.get_subscription`

Get one subscription by id: its status, billing period, whether it is set to cancel, and its price items. Use when the user asks about a specific customer's plan or subscription.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /subscriptions/{{params.subscription_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `subscription_id` | string | **yes** | Stripe subscription id, e.g. "sub_1P9k2VbA1u9Zp". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `cancel_at_period_end` | boolean |  |
| `current_period_end` | integer |  |
| `current_period_start` | integer |  |
| `customer` | string |  |
| `id` | string |  |
| `items` | array of object |  |
| `items[].id` | string |  |
| `items[].price` | object |  |
| `items[].price.id` | string |  |
| `status` | string |  |

Also retrieved by: "what plan is this customer on", "check the status of their subscription", "is this account set to cancel".

### `stripe.list_subscriptions`

List subscriptions, optionally filtered by customer, status, or price. Use when the user asks who is subscribed, what plan a customer is on, or wants a list of active or canceled subscriptions.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /subscriptions`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `customer` | string | no | Only subscriptions for this customer id. |
| `limit` | integer | no | Results per page, max 100. Defaults to 10. |
| `price` | string | no | Only subscriptions that include this price id. |
| `status` | string, one of active, past_due, unpaid, canceled, trialing, all | no | Only subscriptions in this state. Defaults to active. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `data` | array of object |  |
| `data[].cancel_at_period_end` | boolean |  |
| `data[].current_period_end` | integer |  |
| `data[].customer` | string |  |
| `data[].id` | string |  |
| `data[].status` | string |  |
| `has_more` | boolean |  |

Also retrieved by: "who's actively subscribed right now", "show every canceled plan", "find accounts on this specific price".

### `stripe.update_subscription`

Change a subscription's price items, or schedule it to cancel at the end of the current billing period. Use when the user wants to upgrade, downgrade, swap plans, or schedule a future cancellation without ending it now. To end it immediately, use cancel_subscription.

Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `POST /subscriptions/{{params.subscription_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `cancel_at_period_end` | boolean | no | True to end the subscription when the current period finishes, false to un-schedule that. |
| `items` | array of object | no | Replacement price and quantity pairs for the subscription. |
| `items[].id` | string | no | Existing subscription item id, to change its price or quantity. |
| `items[].price` | string | no | Stripe price id. |
| `items[].quantity` | integer | no | Quantity of this price. |
| `proration_behavior` | string, one of create_prorations, none, always_invoice | no | How to prorate a mid-period price change. Defaults to create_prorations. |
| `subscription_id` | string | **yes** | Stripe subscription id to update. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `cancel_at_period_end` | boolean |  |
| `current_period_end` | integer |  |
| `id` | string |  |
| `status` | string |  |

Also retrieved by: "move them to a different plan", "upgrade their subscription tier", "schedule this to end at the period's close", "swap the price on their plan".

### `stripe.cancel_subscription`

End a subscription immediately, stopping future billing. Irreversible; a canceled subscription cannot be resumed and needs a new one. Use when the user wants to cancel, stop, or terminate a subscription right now, not at period end.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). No scopes beyond the connection's defaults. Calls `DELETE /subscriptions/{{params.subscription_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `invoice_now` | boolean | no | True to invoice any outstanding, unbilled usage immediately. |
| `prorate` | boolean | no | True to credit the unused time remaining in the current period. |
| `subscription_id` | string | **yes** | Stripe subscription id to cancel. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `canceled_at` | integer |  |
| `id` | string |  |
| `status` | string |  |

Also retrieved by: "stop billing them right now", "end this subscription immediately", "terminate their plan today, not later", "shut off their recurring charges for good".