Skip to main content
POST
Create a subscription

Authorizations

Authorization
string
header
required

Use sk_test_ keys for sandbox. Use sk_live_ keys for production. Obtain your key from the dashboard.

Body

application/json
customer_id
string
required
Example:

"cus_01JABC..."

plan_id
string
required
Example:

"pln_01JABC..."

default_payment_method_id
string

Card token from Nomba. Required for card-rail subscriptions.

Example:

"tok_test_visa"

preferred_rail
enum<string>
default:card
Available options:
card,
transfer,
direct_debit
Example:

"card"

quantity
integer
default:1
Example:

1

metadata
object

Response

201 - application/json

Subscription created

object
enum<string>
Available options:
subscription
id
string
Example:

"sub_01JABC..."

state
enum<string>
Available options:
incomplete,
active,
trialing,
past_due,
grace,
delinquent,
paused,
canceled
Example:

"active"

current_period_start
string<date-time>
current_period_end
string<date-time>
trial_end_at
string<date-time> | null
next_bill_at
string<date-time>
cancel_at_period_end
boolean

True when the subscription is set to cancel at period end (still active until then).

Example:

false

canceled_at
string<date-time> | null
has_card
boolean

Whether a card token is on file. Transfer-funded subs have none.

Example:

true

scheduled_change
object | null

A pending period-end plan change (e.g. a scheduled downgrade).