v1

latestOpenAPI 3.0.22026-07-2667277423.4 KB

Subscriptions

Subscription: Create

Create a new subscription. A subscription represents a recurring payment. Recurring payments may be on a weekly, monthly, or yearly basis, specified by the period parameter.

In order to create a subscription, a customer ID must be supplied. The customer object contains saved payment info, which is regularly charged by the subscription.

A subscription can't be modified once it's created. To change a subscription, you must delete it and create a new one.

post/subscriptions

Request body

customerstring required

A unique 25-character alphanumeric resource identifier.

amountinteger required

Amount greater than or equal to 0, in the lowest denomination of the currency (e.g. cents for USD).

currency'JPY' | 'USD' | 'EUR' | 'TWD' | 'KRW' | 'PLN' | 'GBP' | 'HKD' | 'SGD' | 'NZD' | 'AUD' | 'IDR' | 'MYR' | 'PHP' | 'THB' | 'CNY' | 'BRL' | 'CHF' | 'CAD' | 'VND' required

3-letter ISO currency code.

period'weekly' | 'monthly' | 'yearly' required

Interval for subscription payments

metadataobject

Store any additional data you want to associate with the subscription. The object's keys and values must be strings. Keys have a maximum length of 30 characters. Values have a maximum length of 2000 characters.

Example request

{
  "currency": "JPY"
}

Response

200 response

idstring required

A unique 25-character alphanumeric resource identifier.

resource'subscription' required

Resource type name, always "subscription".

statusstring required

Current status of the subscription (e.g. "active", "cancelled").

amountinteger required

Amount greater than or equal to 0, in the lowest denomination of the currency (e.g. cents for USD).

currency'JPY' | 'USD' | 'EUR' | 'TWD' | 'KRW' | 'PLN' | 'GBP' | 'HKD' | 'SGD' | 'NZD' | 'AUD' | 'IDR' | 'MYR' | 'PHP' | 'THB' | 'CNY' | 'BRL' | 'CHF' | 'CAD' | 'VND' required

3-letter ISO currency code.

period'weekly' | 'monthly' | 'yearly' required

Interval for subscription payments

dayinteger required

Day of the period on which the subscription is charged.

retry_countinteger required

Number of times payment has been retried after failure.

retry_atstring date-time nullable required

Timestamp of the next scheduled payment retry, or null.

next_capture_atstring date-time required

Timestamp of the next scheduled subscription charge.

created_atstring date-time required

Timestamp when the subscription was created.

ended_atstring date-time nullable required

Timestamp when the subscription ended, or null if still active.

metadataobject required

Arbitrary key-value metadata attached to the subscription.

paymentsUUID[] required

Array of payment UUIDs associated with this subscription.

Example response

{
  "currency": "JPY",
  "customer": {
    "currency": "JPY"
  }
}