Skip to main content
POST
Create Subscription
Subscribe a customer to a plan. The plan’s price, cadence and grace period are copied onto the subscription at this moment. Editing the plan afterwards never changes what this subscriber pays — see Subscriptions.

Request authentication

This endpoint requires a Secret Key (sk_...) passed in either the x-api-key header or as a Bearer token in the Authorization header.

Request parameters

string
required
The id of the plan to subscribe them to.
object
A new customer. Use this or customer_id.
string
An existing customer on your business. Use this or customer.
string
invoice only for now; auto_debit is coming soon. Defaults to invoice.
integer
Overrides the plan’s trial for this subscriber only.
object
Any key-value data you want stored alongside the subscription.

Authorizations

x-api-key
string
header
required

Body

application/json
plan
string
required

Plan id.

Example:

"6712f0a1b9c4e2d3f4a5b6c7"

customer_id
string

An existing customer. Use this or customer.

customer
object

A new customer. Use this or customer_id.

collection_mode
enum<string>
default:invoice

Only invoice is accepted today. auto_debit (pull against an approved on-chain allowance) is coming soon; sending it is rejected.

Available options:
invoice
trial_days
integer

Overrides the plan's trial for this subscriber.

metadata
object

Response

The subscription. Send the customer to checkout_url to take the first payment.

A single subscription.

message
string
data
object