Skip to main content
POST
billing.subscription.create

Authorizations

Authorization
string
header
required

API key: sk_live_…

Headers

Idempotency-Key
string
required

Required: this capability has an external effect.

Maximum string length: 255
Pramaan-Account
string

Optional. One of your account ids (GET /v1/accounts): run on that account, whatever your routing rules say. The response header X-Pramaan-Account names the account that ran.

Pramaan-End-User
string

Optional. Your own tag for your end user: a sticky: end_user rule keeps them on the account that first served them.

Maximum string length: 256
Pramaan-End-User-Group
string

Optional. Your end user's group, matched by rules with endUserGroup.

Maximum string length: 64

Body

application/json
subscriptionId
string

Your subscription record ID (plan form).

Required string length: 1 - 128
Pattern: ^[A-Za-z0-9_-]+$
planId
string

Your plan record ID (plan form).

Required string length: 1 - 128
Pattern: ^[A-Za-z0-9_-]+$
customerEmail
string<email>

Customer email for authorization notifications (plan form).

Maximum string length: 200
Pattern: ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
customerPhone
string

Customer phone for authorization notifications (plan form).

Required string length: 1 - 12
Pattern: ^[0-9]{10,12}$
customerName
string

Customer name (plan form).

Required string length: 1 - 100
authorizationAmount
object

Amount used for authorization, refundable as selected (plan form).

refundAuthorization
boolean

Refund the authorization amount automatically; default true (plan form).

expiresAt
string<date-time>

Date and time with timezone, ISO 8601.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
firstChargeAt
string<date-time>

Date and time with timezone, ISO 8601.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
notificationChannels
enum<string>[]

Send the authorization request by these channels; default email (plan form).

Required array length: 1 - 2 elements
Available options:
email,
sms
customerId
string

Customer to charge (schedule form).

Required string length: 1 - 128
Pattern: ^[A-Za-z0-9_-]+$
amount
object

Recurring amount in minor units of an explicit currency (schedule form).

interval
enum<string>

Unit between charges.

Available options:
day,
week,
month,
year
intervalCount
number
Required range: 1 <= x <= 365
description
string

Description shown on the payment (schedule form).

Required string length: 1 - 255
method
enum<string>

Payment method category.

Available options:
card,
bank_debit,
bank_transfer,
wallet
applicationFee
object

Fee collected by your authorized application connection (schedule form).

times
number

Total charge count; omit to continue until canceled (schedule form).

Required range: 1 <= x <= 10000
startDate
string

First charge date, YYYY-MM-DD (schedule form).

Required string length: 1 - 10
Pattern: ^\d{4}-\d{2}-\d{2}$
mandateId
string

Authorization for the charges, belonging to this customer (schedule form).

Required string length: 1 - 128
Pattern: ^[A-Za-z0-9_-]+$
metadata
object

Optional business labels stored in your payment account; do not include secrets.

Response

The result

subscriptionId
string
required

The subscription's id.

status
enum<string>
required

Subscription state. Never "active" unless the billing account said so; anything unrecognized is "unknown".

Available options:
active,
trialing,
past_due,
paused,
canceled,
expired,
pending,
failed,
unknown
customerId
string

The customer it belongs to.

recurringAmount
object

Charge per billing period, before tax.

interval
enum<string>

Billing period unit.

Available options:
day,
week,
month,
year
intervalCount
number

Number of intervals between charges.

quantity
number

Units subscribed to.

cancelAtPeriodEnd
boolean

True when the subscription ends at the end of the current period.

currentPeriodEnd
string

End of the current paid period, ISO 8601.

nextBillingAt
string

Next charge time, ISO 8601.

canceledAt
string

When it was canceled, ISO 8601.

createdAt
string

When it was created, ISO 8601.