Before you begin

Create at least one product and price in your catalog
Create a customer with a payment method on file
Decide on a billing interval (daily, weekly, monthly, or yearly)

Create a subscription

Dashboard

API

Python SDK

Go to Billing > Subscriptions in the sidebar
Click Create Subscription
Select a customer
Add one or more prices with quantities
Set the billing interval and period start date
Configure payment terms and collection method
Click Create

The subscription is created and the first invoice is generated immediately.

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

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.

To set a default processor for your account:

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

Or via API:

$ 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:

$ 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:

$ 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:

$ 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:

$ 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

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

See Subscription lifecycle for details on state transitions.