> 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/concepts/resources/nilus/batch/batch-sources/stripe.md). # Stripe [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= ``` ## Supported objects | Object | Merge key | Strategy | Description | | ----------------------- | --------- | -------- | ------------------------------------ | | `charge` | `id` | merge | Payment charges. | | `payment_intent` | `id` | merge | Payment intents. | | `payment_method` | `id` | merge | Saved payment methods. | | `refund` | `id` | merge | Refunds. | | `payout` | `id` | merge | Payouts to bank accounts. | | `customer` | `id` | merge | Customer records. | | `subscription` | `id` | merge | Customer subscriptions. | | `subscription_item` | `id` | merge | Individual subscription items. | | `subscription_schedule` | `id` | merge | Scheduled subscription updates. | | `product` | `id` | merge | Product catalog. | | `price` | `id` | merge | Product prices. | | `coupon` | `id` | replace | Coupons. | | `promotion_code` | `id` | merge | Promotion codes. | | `invoice` | `id` | merge | Customer invoices. | | `invoice_item` | `id` | merge | Invoice line items. | | `credit_note` | `id` | merge | Credit notes. | | `tax_rate` | `id` | replace | Tax rates. | | `balance_transaction` | `id` | merge | Balance transaction history. | | `event` | `id` | append | Event stream (account-level events). | | `setup_intent` | `id` | merge | Setup intents for future payments. | | `webhook_endpoint` | `id` | replace | Configured webhook endpoints. | ### Loading modes Stripe objects can be loaded in three modes by appending a suffix to `source_table`: | Mode | Suffix | When to use | | ---------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Async (default) | `` | Initial loads and large datasets. Parallel and fast; record order is not guaranteed. | | Sync | `:sync` | Smaller datasets that benefit from ordered, sequential loading. | | Sync incremental | `:sync:incremental` | Subsequent runs after an initial load: only fetches records created/updated since the last run, using Stripe's `created` field. Must be combined with `sync`. | Example: ```yaml source: address: stripe://?api_key={STRIPE_API_KEY} options: source_table: charge:sync:incremental ``` ## Source options | Option | Required | Description | | ----------------- | -------- | -------------------------------------------------------------------------- | | `source_table` | Yes | One of the resources in the [supported objects](#supported-objects) table. | | `incremental_key` | No | Not used. Nilus manages refresh cadence per resource internally. | ## 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 mode**: 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 `: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 sample configs](/concepts/resources/nilus/batch/sample-configs.md) * [Understanding Batch Pipeline Config](/concepts/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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://v2.dataos.info/concepts/resources/nilus/batch/batch-sources/stripe.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.