> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/references/resources/nilus/batch/batch-sources/stripe.md).

# Stripe

Stripe batch source. Extracts payment objects (charges, customers, subscriptions, invoices, balance transactions) in async, sync, or sync-incremental loading modes.

[Stripe](https://stripe.com/) is a financial-infrastructure platform for online payments, subscriptions, billing, and marketplaces. Nilus uses Stripe as a batch source to extract charges, customers, subscriptions, invoices, balance transactions, and other Stripe objects into a downstream warehouse for finance and revenue reporting.

Under the hood, Nilus calls the [Stripe API](https://docs.stripe.com/api) using a secret or restricted key. Each Stripe object is selectable through `source_table`. A loading-mode suffix on `source_table` (`:sync`, `:sync:incremental`) controls how the data is fetched.

## Requirements

Connectivity and credentials must both be in place before the pipeline can run.

### Connectivity

* The Nilus runtime must be able to reach `https://api.stripe.com` over HTTPS.
* Use `sk_test_...` against test data and `sk_live_...` against production. Switching between modes requires a different key.
* Restricted keys must include read permission on every object in `source_table` (e.g. `Charges read`, `Customers read`).

{% hint style="info" %}
Stripe API keys give read access to potentially sensitive payment data. Store the key via Nilus secrets/projections rather than embedding the literal value in YAML.
{% endhint %}

### Required parameters

| Parameter | Required | Default | Description                                                                                                                                  |
| --------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `api_key` | Yes      | -       | Stripe secret or restricted key (`sk_live_...` or `sk_test_...`). Restricted keys are recommended; grant only the read permissions you need. |

### URI format

```
stripe://?api_key=<stripe-api-key>
```

## Supported objects

<table data-search="false"><thead><tr><th>Object</th><th>Merge key</th><th>Strategy</th><th>Description</th></tr></thead><tbody><tr><td><code>charge</code></td><td><code>id</code></td><td>merge</td><td>Payment charges.</td></tr><tr><td><code>payment_intent</code></td><td><code>id</code></td><td>merge</td><td>Payment intents.</td></tr><tr><td><code>payment_method</code></td><td><code>id</code></td><td>merge</td><td>Saved payment methods.</td></tr><tr><td><code>refund</code></td><td><code>id</code></td><td>merge</td><td>Refunds.</td></tr><tr><td><code>payout</code></td><td><code>id</code></td><td>merge</td><td>Payouts to bank accounts.</td></tr><tr><td><code>customer</code></td><td><code>id</code></td><td>merge</td><td>Customer records.</td></tr><tr><td><code>subscription</code></td><td><code>id</code></td><td>merge</td><td>Customer subscriptions.</td></tr><tr><td><code>subscription_item</code></td><td><code>id</code></td><td>merge</td><td>Individual subscription items.</td></tr><tr><td><code>subscription_schedule</code></td><td><code>id</code></td><td>merge</td><td>Scheduled subscription updates.</td></tr><tr><td><code>product</code></td><td><code>id</code></td><td>merge</td><td>Product catalog.</td></tr><tr><td><code>price</code></td><td><code>id</code></td><td>merge</td><td>Product prices.</td></tr><tr><td><code>coupon</code></td><td><code>id</code></td><td>replace</td><td>Coupons.</td></tr><tr><td><code>promotion_code</code></td><td><code>id</code></td><td>merge</td><td>Promotion codes.</td></tr><tr><td><code>invoice</code></td><td><code>id</code></td><td>merge</td><td>Customer invoices.</td></tr><tr><td><code>invoice_item</code></td><td><code>id</code></td><td>merge</td><td>Invoice line items.</td></tr><tr><td><code>credit_note</code></td><td><code>id</code></td><td>merge</td><td>Credit notes.</td></tr><tr><td><code>tax_rate</code></td><td><code>id</code></td><td>replace</td><td>Tax rates.</td></tr><tr><td><code>balance_transaction</code></td><td><code>id</code></td><td>merge</td><td>Balance transaction history.</td></tr><tr><td><code>event</code></td><td><code>id</code></td><td>append</td><td>Event stream (account-level events).</td></tr><tr><td><code>setup_intent</code></td><td><code>id</code></td><td>merge</td><td>Setup intents for future payments.</td></tr><tr><td><code>webhook_endpoint</code></td><td><code>id</code></td><td>replace</td><td>Configured webhook endpoints.</td></tr></tbody></table>

### Loading modes

Stripe objects can be loaded in three modes by appending a suffix to `source_table`:

| Mode             | Suffix                      | When to use                                                                                                                                                                                                                   |
| ---------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Async (default)  | `<object>`                  | Initial loads and large datasets. Full load, parallel and fast; record order is not guaranteed. Replaces the destination table.                                                                                               |
| Sync             | `<object>:sync`             | Smaller datasets that benefit from ordered, sequential loading. Full load; replaces the destination table.                                                                                                                    |
| Sync incremental | `<object>:sync:incremental` | Subsequent runs after an initial load. Fetches only records **created** since the last run, using Stripe's `created` field, and merges on `id`. The first run starts from `interval_start`, or `2010-01-01` if it is not set. |

{% hint style="warning" %}
Sync incremental tracks Stripe's `created` timestamp only. Changes to records created before the last run, such as a charge's status, refunds, or disputes, are **not** picked up. Schedule a periodic full load (`<object>` or `<object>:sync`) if you need those updates.
{% endhint %}

Example:

```yaml
source:
  address: stripe://?api_key={STRIPE_API_KEY}
  options:
    source_table: charge:sync:incremental
```

## Output schema

Nilus pins Stripe API version `2022-11-15`. There is no fixed schema in Nilus for `charge` or any other Stripe object. Columns are created from fields in the API objects Stripe returns for your account. The exact `charge` column list follows the [Stripe Charge object](https://docs.stripe.com/api/charges/object) for that API version and your account data.

At the default `max_table_nesting` value of `"0"`:

* Top-level scalar fields land as columns.
* Nested objects and arrays land as one `json` column each. Set `source.options.max_table_nesting` or `MAX_TABLE_NESTING` to flatten them.
* Fields that are null in every row may not create columns until a non-null value arrives.
* The same rules apply to every Stripe object in the [supported objects](#supported-objects) table.

Typical `charge` columns at the default nesting level are not exhaustive:

| Column                   | Type   | Notes                                                |
| ------------------------ | ------ | ---------------------------------------------------- |
| `id`                     | text   | Merge key.                                           |
| `amount`                 | bigint | Amount in the smallest currency unit.                |
| `currency`               | text   |                                                      |
| `status`                 | text   |                                                      |
| `created`                | bigint | Unix timestamp. `:sync:incremental` uses this field. |
| `billing_details`        | json   |                                                      |
| `outcome`                | json   |                                                      |
| `payment_method_details` | json   |                                                      |
| `metadata`               | json   |                                                      |
| `refunds`                | json   |                                                      |

{% hint style="info" %}
Some destinations also write load-metadata columns (`_dlt_load_id` / `_dlt_id`, or `_nilus_load_id` / `_nilus_id`). They are not Stripe fields and are not guaranteed on every destination. Sync incremental keeps its position in pipeline state, so no cursor column is added to the table.
{% endhint %}

### Schema changes

Nilus does not enforce a schema contract on Stripe data:

* A new Stripe field adds a nullable column.
* If a field type changes, Nilus keeps the existing column and adds a variant column for the new type, such as `amount__v_text`.
* Columns are never dropped, even if Stripe stops returning the field.

## Source options

| Option              | Required | Description                                                                                                                  |
| ------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `source_table`      | Yes      | One of the resources in the [supported objects](#supported-objects) table.                                                   |
| `incremental_key`   | No       | Not supported. Nilus rejects it for Stripe; use the `:sync:incremental` suffix instead.                                      |
| `max_table_nesting` | No       | String. Default `"0"`: nested Stripe objects land as `json` columns. Raise to flatten. Also accepted as `MAX_TABLE_NESTING`. |

## Sink options

| Option                 | Required | Description                                                                                               |
| ---------------------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `dest_table`           | Yes      | Destination table name. Use one stable target per source resource so re-runs merge cleanly.               |
| `incremental_strategy` | Yes      | Destination write behavior. Use `merge` for time-aware resources, `replace` for snapshot-style resources. |

## Sample Nilus config

```yaml
name: stripe-charge-sync-incremental-batch
version: v1alpha
type: nilus
spec:
  type: batch
  compute: universe-compute
  source:
    address: stripe://?api_key={STRIPE_API_KEY}
    options:
      source_table: charge:sync:incremental
  sink:
    address: dataos://warehouse?purpose=rw
    options:
      dest_table: finance.stripe_charges
      incremental_strategy: merge
```

## Behavior and capabilities

* **Pipeline type**: Stripe runs as a `batch` source.
* **Object selection**: set `source.options.source_table` to one object from the supported objects table. Use one pipeline or destination table per Stripe object.
* **Fetch semantics**: async mode is the default for initial loads and large datasets. Use `:sync:incremental` after the initial load when the object supports created-time incremental fetching.
* **API limits**: Stripe applies per-account rate limits. Stagger high-volume objects and avoid running many object pipelines at the same time.
* **Destination strategy**: use `merge` for objects with stable IDs and change history, `replace` for snapshot-style objects, and `append` for account-level events.

## Troubleshooting

| Symptom                 | Likely cause                                                                       | Resolution                                                                                   |
| ----------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `401 Invalid API Key`   | Wrong key prefix (test vs live) or revoked.                                        | Issue a new key in Stripe Dashboard → Developers → API keys and re-supply via Nilus secrets. |
| `403 Forbidden`         | Restricted key missing the required read permission for the requested object.      | Edit the restricted key permissions in Stripe Dashboard or use a secret key.                 |
| `No such resource`      | Object name does not match Stripe's resource (e.g. `charges` instead of `charge`). | Use singular names from the Supported objects table above.                                   |
| Re-runs reload all data | Loading mode is async (default).                                                   | Switch to `<object>:sync:incremental` once initial load completes.                           |
| Rate-limited (`429`)    | Per-account rate limit exceeded.                                                   | Switch to async mode for large reads, or stagger schedules across objects.                   |

## Related docs

* [Batch data movement](https://v2.dataos.info/references/resources/nilus/batch.md)
* [Batch sample configs](https://v2.dataos.info/references/resources/nilus/batch/sample-configs.md)
* [Batch pipeline config](https://v2.dataos.info/references/resources/nilus/batch/pipeline-config.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://v2.dataos.info/references/resources/nilus/batch/batch-sources/stripe.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
