# Paddle

Paddle is a merchant of record platform for SaaS and digital product businesses, handling payments, subscriptions, tax compliance, and billing. The Sling Paddle connector extracts data from the Paddle Billing API, supporting products, prices, customers, subscriptions, transactions, adjustments, events, 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 Paddle API key (starts with `pdl_`)

**Inputs:**

* `environment` (optional) -> API environment: `api` for live, `sandbox-api` for sandbox (default: `sandbox-api`)
* `anchor_date` (optional) -> Starting date for historical data extraction (default: 1 year ago). Format: `YYYY-MM-DDTHH:MM:SSZ`

### Getting Your API Key

1. Log in to your [Paddle Dashboard](https://vendors.paddle.com) (or [Sandbox Dashboard](https://sandbox-vendors.paddle.com) for testing)
2. Navigate to **Developer Tools** > **Authentication**
3. Click **New API key**
4. Enter a name, select the required permissions (read access), and click **Save**
5. Copy the generated API key

{% hint style="warning" %}
**Important:** API keys start with `pdl_live_apikey_` for production or `pdl_sdbx_apikey_` for sandbox environments. Ensure you select appropriate read permissions for the endpoints you want to sync.
{% endhint %}

### Using `sling conns`

{% code overflow="wrap" %}

```bash
sling conns set PADDLE type=api spec=paddle secrets='{ api_key: your_paddle_api_key }' inputs='{ environment: sandbox-api }'
```

{% 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 PADDLE='{ type: api, spec: paddle, secrets: { api_key: "your_paddle_api_key" }, inputs: { environment: "api" } }'
```

{% 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:
  PADDLE:
    type: api
    spec: paddle
    secrets:
      api_key: "your_paddle_api_key"
    inputs:
      environment: "api"  # or "sandbox-api" for testing
```

## Replication

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

```yaml
source: PADDLE
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: public.paddle_{stream_name}

streams:
  # sync all endpoints
  '*':

  # use incremental mode for high-volume endpoints
  transactions:
    mode: incremental
  events:
    mode: incremental
```

## Endpoints

| Endpoint             | Description                         | Incremental |
| -------------------- | ----------------------------------- | ----------- |
| `products`           | Products in the catalog             | Yes         |
| `prices`             | Prices for products                 | Yes         |
| `discounts`          | Discount codes and rules            | Yes         |
| `customers`          | Customer records                    | Yes         |
| `customer_addresses` | Addresses for each customer         | No          |
| `businesses`         | Business entities for each customer | No          |
| `subscriptions`      | Recurring subscriptions             | Yes         |
| `transactions`       | Payment transactions                | Yes         |
| `adjustments`        | Refunds, credits, and chargebacks   | Yes         |
| `events`             | Audit log of all changes            | Yes         |
| `event_types`        | Available event type definitions    | No          |
| `reports`            | Generated reports                   | Yes         |

## Notes

* **Sandbox vs Live**: Set the `environment` input to `sandbox-api` for testing or `api` for production data.
* **Rate Limits**: The Paddle API allows 240 requests per minute per IP. The connector uses conservative rate limiting (4 req/s) to stay well within limits.
* **Incremental Sync**: Most endpoints support incremental sync using the `updated_at` timestamp filter. The `events` endpoint uses `occurred_at`.
* **Child Endpoints**: `customer_addresses` and `businesses` are child endpoints that iterate over customer IDs from the `customers` endpoint. They run in `full-refresh` mode.

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).