> ## Documentation Index
> Fetch the complete documentation index at: https://filament.getgalaxy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Stripe

> Read charges, payment intents, invoices, subscriptions, and the balance ledger from a Stripe account

The Stripe source reads customers, payments, invoices, subscriptions, catalog
objects, balance transactions, and events. It is built with an
[HTTP manifest](/pages/connectors/building-a-connector/http-manifests) and is
**beta**. Its resources are stable, though future releases may add columns.

## Configuration

| Field     | Scope      | Default | Description                                                                                                           |
| --------- | ---------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
| `api_key` | Connection |         | Required. Secret. Restricted key (`rk_…`) with read permissions on the extracted resources, or a secret key (`sk_…`). |

## Resources

| Resource                                           | Parent          | Notes                                                                       |
| -------------------------------------------------- | --------------- | --------------------------------------------------------------------------- |
| `customers`                                        |                 | Connection probe                                                            |
| `charges`                                          |                 | Incremental                                                                 |
| `payment_intents`                                  |                 | Incremental. `raw` preserves `client_secret`                                |
| `refunds`                                          |                 | Incremental. `status` settles after creation                                |
| `disputes`                                         |                 | Incremental                                                                 |
| `balance_transactions`                             |                 | Incremental. Ledger with per-transaction fee splits                         |
| `payouts`                                          |                 | Incremental                                                                 |
| `invoices`                                         |                 | Incremental. Embedded `lines` truncates at 10                               |
| `invoice_line_items`                               | `invoices`      | One request per invoice. The complete line set                              |
| `credit_notes`                                     |                 | Incremental                                                                 |
| `subscriptions`                                    |                 | `status=all` keeps canceled subscriptions. Embedded `items` truncates at 10 |
| `subscription_items`                               | `subscriptions` | One request per subscription. Only source of the item-level billing period  |
| `products`, `prices`, `coupons`, `promotion_codes` |                 | Catalog objects                                                             |
| `checkout_sessions`                                |                 | Incremental                                                                 |
| `setup_intents`                                    |                 | `raw` preserves `client_secret`                                             |
| `payment_methods`                                  |                 | No `created` list filter, so never incremental                              |
| `tax_rates`                                        |                 |                                                                             |
| `events`                                           |                 | Incremental. 30-day retention                                               |

The two fan-out children exist because Stripe embeds `lines` and `items` as
lists that truncate at 10 with their own `has_more`. The parent keeps the
embedded copy as `raw` JSON for reference, and the child resource is the
complete set.

<Warning>
  `payment_intents.raw` and `setup_intents.raw` contain `client_secret`. Treat
  those destination tables as sensitive. Stripe retains events for 30 days, so
  a pipeline paused longer than that cannot recover the missing event history.
</Warning>

## Modes

All resources support full reads. If interrupted, a full read of a top-level
resource resumes after its last completed page.

The incremental resources are `charges`, `payment_intents`, `refunds`,
`disputes`, `balance_transactions`, `payouts`, `invoices`, `credit_notes`,
`checkout_sessions`, and `events`. All follow the same pattern.

|                   |                                               |
| ----------------- | --------------------------------------------- |
| Cursor field      | `created` (Unix epoch, `int64`)               |
| Request parameter | `created[gte]` (query)                        |
| Comparator        | `numeric`                                     |
| Checkpoint key    | `<resource>_created` (e.g. `charges_created`) |
| Overlap           | none by default                               |

The cursor field is fixed by the manifest. Only a lookback window is
user-configurable, which the numeric comparator supports. A lookback matters
here because `created` never changes. A refund that settles from `pending` to
`succeeded`, or a dispute that resolves, is not re-read by an incremental run
unless a lookback window covers it. Use full runs or the `events` feed to
capture post-creation mutations.

## Behavior

* **Auth**: HTTP basic with the API key as the username and no password,
  matching `curl -u sk_test_…:`.
* **Pagination**: Stripe returns no next-page token. The cursor is the id of
  the last record on the page (`data.-1.id`), echoed back as
  `starting_after`, with `has_more` as the terminator and `limit=100` per
  page.
* **API version**: pinned via `Stripe-Version: 2026-07-29.dahlia`, so payload
  response schema is set by the manifest, not the account's dashboard
  setting. The exception is `events.data.object`, which is rendered at the
  version current when each event was created.
* **Rate limiting**: a static 8 requests/second limiter, held below Stripe's
  25 rps sandbox ceiling since one limiter is shared across all concurrently
  extracting resources. Stripe publishes no rate-limit response headers, so
  there is no dynamic block.
* **Timestamps**: every Stripe timestamp is a Unix epoch integer typed
  `int64`, not `timestamptz`.