API ReferenceSubscriptions

Create Subscription

View as Markdown
Create a subscription and optionally process payment.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

account_idstringRequired

Request

This endpoint expects an object.
customer_idstringRequired
period_startdatetimeRequired
itemslist of objectsRequired
currencyenum or nullOptional
ISO 4217 currency codes.
period_enddatetime or nullOptional
descriptionstring or nullOptional
billing_intervalstring or nullOptional
billing_interval_countinteger or nullOptional>=1
trial_startdatetime or nullOptional
trial_enddatetime or nullOptional
total_billing_cyclesinteger or nullOptional>=1
contract_auto_renewboolean or nullOptional
collection_methodenumOptional
net_dinteger or nullOptional>=0
statement_descriptor_suffixstring or nullOptional
Statement descriptor suffix for this subscription. When set, overrides the default descriptor on renewals. Validated against the account's effective prefix.
cancel_at_period_endboolean or nullOptional
default_payment_method_idstring or nullOptional
metadatamap from strings to any or nullOptional
process_paymentboolean or nullOptionalDefaults to false
idempotency_keystring or nullOptional
processor_idstring or nullOptional
coupon_idstring or nullOptional
promotion_codestring or nullOptional
custom_fieldsmap from strings to any or nullOptional
Custom field values to set on this subscription. Keys must match defined field keys for the subscription entity type. Set a key to null to delete that field's value.
simulation_idstring or nullOptional
ID of simulation this subscription belongs to. Only for simulated subscriptions.

Response

Successful Response
idstring
stateenum

The possible states of a subscription.

Most are self-explanatory: it starts INCOMPLETE (created, not yet paid for), or TRIALING / SCHEDULED, becomes ACTIVE once paid, and can end up PAUSED, PAST_DUE (a payment failed), or CANCELLED.

ACTIVE_UNSETTLED is the unusual one, added for slow bank rails like SEPA where the money does not arrive until days later. It means: “we already let the customer in at checkout, but their payment has not actually settled yet.” A subscription is created straight into this state — nothing ever moves INTO it from another state. It has exactly two ways out: it becomes ACTIVE if the payment settles, or CANCELLED if the payment fails, times out, or is later reversed (a chargeback).

currencyenum
ISO 4217 currency codes.
descriptionstring or null
current_period_startdatetime
current_period_enddatetime
trial_startdatetime or null
trial_enddatetime or null
created_atdatetime
updated_atdatetime
itemslist of objects
customerobject
collection_methodenum
payment_methodobject or null
Payment method API response model.
billing_intervalstring or nullOptional
billing_interval_countinteger or nullOptional
paused_atdatetime or nullOptional
resumes_atdatetime or nullOptional
pause_at_endboolean or nullOptional
cancel_at_period_endboolean or nullOptional
cancel_atdatetime or nullOptional
cancellation_refund_optionenum or nullOptional

Refund options when cancelling a subscription.

  • NONE: Cancel with no refund (current behavior)
  • FULL: Refund full current period amount
  • PRORATED: Refund unused portion of current period
  • CANCEL_UNPAID: Use dunning_end_behavior for unpaid invoices
cancellation_detailsobject or nullOptional

Details about why a subscription was cancelled.

All fields are optional — callers can provide any combination. Stored as JSONB on the subscription entity.

net_dinteger or nullOptional
statement_descriptor_suffixstring or nullOptional
Statement descriptor suffix for this subscription.
total_billing_cyclesinteger or nullOptional
remaining_billing_cyclesinteger or nullOptional
contract_auto_renewboolean or nullOptional
discountobject or nullOptional
Response schema for discount data.
last_successful_processor_idstring or nullOptional
metadatamap from strings to any or nullOptional
split_from_subscriptionstring or nullOptional

ID of the subscription this was split from (cross-interval plan change).

split_to_subscriptionslist of strings or nullOptional

IDs of subscriptions created from this one (cross-interval plan change).

pending_plan_changeobject or nullOptional
Pending plan change scheduled for period end. Present when a deferred plan change is awaiting execution.
custom_fieldsmap from strings to any or nullOptional

Custom field values. Only included when expand=custom_fields is specified.

Errors

422
Unprocessable Entity Error