***

title: Create a subscription
subtitle: >-
Start billing a customer on a recurring schedule by creating a subscription
with one or more prices.
------------------------

# Before you begin

* Create at least one [product and price](/guides/product-catalog) in your catalog
* Create a [customer](/api-reference) with a payment method on file
* Decide on a billing interval (daily, weekly, monthly, or yearly)

# Create a subscription

<Tabs>
  <Tab title="Dashboard">
    1. Go to **Billing > Subscriptions** in the sidebar
    2. Click **Create Subscription**
    3. Select a customer
    4. Add one or more prices with quantities
    5. Set the billing interval and period start date
    6. Configure payment terms and collection method
    7. Click **Create**

    The subscription is created and the first invoice is generated immediately.
  </Tab>

  <Tab title="API">
    ```bash
    curl -X POST https://api.paymentkit.com/api/{account_id}/subscriptions \
    -H "Authorization: Bearer sk_live_..." \
    -H "Content-Type: application/json" \
    -d '{
      "customer_id": "cus_abc123",
      "currency": "USD",
      "period_start": "2026-02-01T00:00:00Z",
      "billing_interval": "month",
      "billing_interval_count": 1,
      "collection_method": "charge_automatically",
      "processor_id": "proc_live_abc123",
      "items": [
        {
          "price_id": "price_monthly_pro",
          "quantity": 1
        }
      ]
    }'
    ```

    The response includes the full subscription object with its current state.

    <Note>
      If you omit `processor_id`, PaymentKit uses your account's default processor. Ensure a default is configured or the request will fail.
    </Note>
  </Tab>

  <Tab title="Python SDK">
    ```python
    from paymentkit import PaymentKit

    client = PaymentKit(api_key="sk_live_...")

    subscription = client.subscriptions.create(
        account_id="acc_abc123",
        customer_id="cus_abc123",
        currency="USD",
        period_start="2026-02-01T00:00:00Z",
        billing_interval="month",
        billing_interval_count=1,
        collection_method="charge_automatically",
        processor_id="proc_live_abc123",  # Optional: uses default if omitted
        items=[
            {"price_id": "price_monthly_pro", "quantity": 1}
        ]
    )
    ```
  </Tab>
</Tabs>

# Configuration options

## Billing interval

Control how often the customer is billed:

| Field                    | Description                                                                               |
| ------------------------ | ----------------------------------------------------------------------------------------- |
| `billing_interval`       | The interval unit: `day`, `week`, `month`, or `year`                                      |
| `billing_interval_count` | Number of intervals between billings. For example, `3` with `month` bills every 3 months. |

## Collection method

| Method                 | Behavior                                                                    |
| ---------------------- | --------------------------------------------------------------------------- |
| `charge_automatically` | PaymentKit charges the customer's default payment method at each renewal.   |
| `send_invoice`         | PaymentKit generates an invoice and waits for the customer to pay manually. |

## Payment terms

Set `net_d` to control when invoices are due for payment. A value of `0` means due immediately. A value of `30` gives the customer 30 days after invoice finalization.

## Payment processor

Specify which payment processor to use for charging the subscription:

| Field          | Description                                                           |
| -------------- | --------------------------------------------------------------------- |
| `processor_id` | External ID of the payment processor to use (e.g., `proc_stg_abc123`) |

**Fallback behavior:**

* If `processor_id` is not provided, PaymentKit uses the account's default processor
* If no default processor is configured for the account, the request **fails with an error**

<Warning>
  You must either pass an explicit `processor_id` or have a default processor configured for your account. If neither is set, subscription creation will fail.
</Warning>

To set a default processor for your account:

1. Go to **Settings > Payment Processors** in the dashboard
2. Click the three-dot menu on a processor
3. Select **Set as Default**

Or via API:

```bash
curl -X POST https://api.paymentkit.com/api/{account_id}/processors/{processor_id}/set-default \
-H "Authorization: Bearer sk_live_..."
```

# Add a trial period

Offer a free trial before the first charge by setting trial dates:

```bash
curl -X POST https://api.paymentkit.com/api/{account_id}/subscriptions \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
  "customer_id": "cus_abc123",
  "currency": "USD",
  "period_start": "2026-02-01T00:00:00Z",
  "billing_interval": "month",
  "billing_interval_count": 1,
  "collection_method": "charge_automatically",
  "trial_start": "2026-02-01T00:00:00Z",
  "trial_end": "2026-02-15T00:00:00Z",
  "items": [
    {"price_id": "price_monthly_pro", "quantity": 1}
  ]
}'
```

During the trial:

* The subscription is in **Trialing** state
* A `$0` invoice is generated for the trial period
* Three days before the trial ends, a `subscription.trial_will_end` event fires
* At trial end, the subscription activates and the first paid invoice is created

# Apply a discount

Attach a coupon or promotion code at creation:

```bash
curl -X POST https://api.paymentkit.com/api/{account_id}/subscriptions \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
  "customer_id": "cus_abc123",
  "currency": "USD",
  "period_start": "2026-02-01T00:00:00Z",
  "billing_interval": "month",
  "billing_interval_count": 1,
  "collection_method": "charge_automatically",
  "coupon_id": "cpn_welcome20",
  "items": [
    {"price_id": "price_monthly_pro", "quantity": 1}
  ]
}'
```

Use `coupon_id` for a direct coupon reference, or `promotion_code` for a customer-facing code. If both are provided, the coupon referenced by the promotion code must match the given `coupon_id`.

# Fixed-term subscriptions

Set `total_billing_cycles` to automatically cancel after a specific number of periods:

```bash
curl -X POST https://api.paymentkit.com/api/{account_id}/subscriptions \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
  "customer_id": "cus_abc123",
  "currency": "USD",
  "period_start": "2026-02-01T00:00:00Z",
  "billing_interval": "month",
  "billing_interval_count": 1,
  "collection_method": "charge_automatically",
  "total_billing_cycles": 12,
  "items": [
    {"price_id": "price_monthly_pro", "quantity": 1}
  ]
}'
```

The subscription cancels automatically after 12 billing cycles complete.

# Multiple items

A subscription can contain multiple prices. Each item represents a line on the recurring invoice:

```bash
curl -X POST https://api.paymentkit.com/api/{account_id}/subscriptions \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
  "customer_id": "cus_abc123",
  "currency": "USD",
  "period_start": "2026-02-01T00:00:00Z",
  "billing_interval": "month",
  "billing_interval_count": 1,
  "collection_method": "charge_automatically",
  "items": [
    {"price_id": "price_base_plan", "quantity": 1},
    {"price_id": "price_addon_seats", "quantity": 5}
  ]
}'
```

# What happens after creation

1. The subscription is created in **Incomplete** state (or **Trialing** if a trial is set)
2. An invoice is generated for the first billing period
3. If `collection_method` is `charge_automatically`, payment is attempted immediately
4. On successful payment, the subscription transitions to **Active**
5. The lifecycle engine schedules the next billing cycle

See [Subscription lifecycle](/guides/billing/subscription-lifecycle) for details on state transitions.