# Stripe

Stripe is a payment processing platform that powers online commerce for businesses of all sizes. The Sling Stripe connector extracts data from the Stripe REST API, supporting charges, customers, invoices, subscriptions, payments, and more.

{% hint style="success" %}
**CLI Pro Required**: APIs require a [CLI Pro token](https://docs.slingdata.io/sling-cli/cli-pro) or [Platform Plan](https://docs.slingdata.io/sling-platform/platform).
{% endhint %}

## Setup

The following credentials and inputs are accepted:

**Secrets:**

* `api_key` **(required)** -> Your Stripe Secret API Key
* `api_version` (optional) -> Stripe API version to use (default: `2023-10-16`)

**Inputs:**

* `anchor_date` (optional) -> The starting date for historical data extraction (default: 1 year ago). Format: `YYYY-MM-DD`

### Getting Your API Key

1. Log in to your [Stripe Dashboard](https://dashboard.stripe.com/)
2. Go to **Developers** > **API keys**
3. Copy your **Secret key** (starts with `sk_live_` for production or `sk_test_` for test mode)

{% hint style="warning" %}
**Important:** Use your Secret key, not the Publishable key. The Secret key has read access to your Stripe data.
{% endhint %}

### Using `sling conns`

Here are examples of setting a connection named `STRIPE`. We must provide the `type=api` property:

{% code overflow="wrap" %}

```bash
sling conns set STRIPE type=api spec=stripe secrets='{ api_key: sk_live_xxxxxxxxxxxx }'
```

{% endcode %}

### Environment Variable

See [here](https://docs.slingdata.io/sling-cli/environment#dot-env-file-.env.sling) to learn more about the `.env.sling` file.

{% code overflow="wrap" %}

```bash
export STRIPE='{ type: api, spec: stripe, secrets: { api_key: "sk_live_xxxxxxxxxxxx" } }'
```

{% endcode %}

### Sling Env File YAML

See [here](https://docs.slingdata.io/sling-cli/environment#sling-env-file-env.yaml) to learn more about the sling `env.yaml` file.

```yaml
connections:
  STRIPE:
    type: api
    spec: stripe
    secrets:
      api_key: "sk_live_xxxxxxxxxxxx"
```

**With anchor date for historical data:**

```yaml
connections:
  STRIPE:
    type: api
    spec: stripe
    secrets:
      api_key: "sk_live_xxxxxxxxxxxx"
    inputs:
      anchor_date: "2020-01-01"
```

## Replication

Here's an example replication configuration to sync Stripe data to a PostgreSQL database:

```yaml
source: STRIPE
target: MY_POSTGRES

defaults:
  mode: incremental
  object: stripe.{stream_name}

streams:
  # sync all endpoints
  '*':

  # Exclude child endpoints if not needed
  credit_note_line_item:
    disabled: true
  setup_attempt:
    disabled: true
```

**Full refresh example for reference data:**

```yaml
source: STRIPE
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: stripe.{stream_name}

streams:
  # Reference data (no incremental support)
  account:
  plan:
  price:
  product:
  payment_method:
```

## Endpoints

### Core Payment Data

| Endpoint         | Description                | Incremental |
| ---------------- | -------------------------- | ----------- |
| `account`        | Stripe account information | No          |
| `charge`         | Payment charges            | Yes         |
| `payment_intent` | Payment intents            | Yes         |
| `payment_method` | Saved payment methods      | No          |
| `payout`         | Payouts to bank accounts   | Yes         |
| `refund`         | Refunds on charges         | Yes         |

### Customers & Subscriptions

| Endpoint                       | Description                         | Incremental |
| ------------------------------ | ----------------------------------- | ----------- |
| `customer`                     | Customer records with discount info | Yes         |
| `customer_balance_transaction` | Customer balance transactions       | No (child)  |
| `subscription`                 | Active and canceled subscriptions   | Yes         |
| `subscription_item`            | Line items in subscriptions         | No (child)  |

### Billing & Invoicing

| Endpoint                | Description                 | Incremental          |
| ----------------------- | --------------------------- | -------------------- |
| `invoice`               | Invoices with discount info | Yes                  |
| `invoice_item`          | Invoice line items          | Yes                  |
| `invoice_line_item`     | Detailed invoice lines      | No (child)           |
| `credit_note`           | Credit notes                | No                   |
| `credit_note_line_item` | Credit note line items      | No (child, disabled) |
| `coupon`                | Discount coupons            | Yes                  |

### Products & Pricing

| Endpoint  | Description                 | Incremental |
| --------- | --------------------------- | ----------- |
| `plan`    | Subscription plans (legacy) | No          |
| `price`   | Prices for products         | No          |
| `product` | Products in your catalog    | No          |

### Setup & Configuration

| Endpoint        | Description                       | Incremental |
| --------------- | --------------------------------- | ----------- |
| `setup_intent`  | Setup intents for future payments | Yes         |
| `setup_attempt` | Setup attempt details             | No (child)  |
| `dispute`       | Issuing disputes                  | Yes         |

### Events & Updates

| Endpoint   | Description                          | Incremental |
| ---------- | ------------------------------------ | ----------- |
| `event`    | Stripe events (30-day retention)     | Yes         |
| `*_update` | Update endpoints for merging changes | No          |

To discover available endpoints:

```bash
sling conns discover STRIPE
```

## Incremental Sync

The Stripe connector uses time-based incremental sync with the `created` timestamp:

* **First run:** Fetches all records from `anchor_date` (default: 1 year ago) to present
* **Subsequent runs:** Only fetches records created after the last sync

### Update Tracking via Events

Stripe doesn't support filtering by `updated_at` timestamps. Instead, the connector uses the **Events API** to track updates:

1. The `event` endpoint fetches events from the last 30 days
2. Events like `customer.updated`, `invoice.updated`, etc. are processed
3. Updated records are pushed to `*_update` endpoints
4. Post-hooks merge updates into the main tables

This ensures you capture both new records (via `created` filter) and updates (via Events API).

{% hint style="info" %}
Stripe only retains events for **30 days**. If you need to capture updates older than 30 days, run a full refresh periodically.
{% endhint %}

## Date Fields

All Unix timestamp fields are automatically converted to proper datetime columns with a `_date` suffix:

| Original Field | Converted Field    |
| -------------- | ------------------ |
| `created`      | `created_date`     |
| `canceled_at`  | `canceled_at_date` |
| `trial_start`  | `trial_start_date` |
| `trial_end`    | `trial_end_date`   |
| ...            | ...                |

## Rate Limiting

The Stripe API has rate limits:

* **Standard accounts:** 100 requests per second (read operations)
* **Connect accounts:** 25 requests per second

The connector automatically:

* Uses conservative rate limiting (20 requests/second)
* Retries with exponential backoff on 429 (rate limit) responses

## Common Use Cases

### Sync Core Payment Data

```yaml
source: STRIPE
target: MY_POSTGRES

defaults:
  mode: incremental
  object: payments.{stream_name}

streams:
  charge:
  payment_intent:
  refund:
  payout:
```

### Sync Customer & Subscription Data

```yaml
source: STRIPE
target: MY_POSTGRES

defaults:
  mode: incremental
  object: subscriptions.{stream_name}

streams:
  customer:
  subscription:
  subscription_item:
  invoice:
  invoice_line_item:
```

### Full Catalog Sync

```yaml
source: STRIPE
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: catalog.{stream_name}

streams:
  product:
  price:
  plan:
  coupon:
```

If you are facing issues connecting, please reach out to us at <support@slingdata.io>, on [discord](https://discord.gg/q5xtaSNDvp) or open a Github Issue [here](https://github.com/slingdata-io/sling-cli/issues).