Subscriptions
A subscription is a resource used to periodically charge a customer. It is created using a transaction token specifically requested for subscription use. Subscriptions can only be created if your account is verified.
Subscription billing will be charged at the interval specified at the time of creation. They can be canceled at any time.
The merchant can set the interval and number of retries for failed subscription payments, and if the payment fails a set number of consecutive times, the recurring billing will be stopped.
A charge is created immediately upon creating a subscription.
It is recommended to use webhooks to be alerted of subscriptions events. The SUBSCRIPTION_PAYMENT event will notify you when a successful payment has been made. The SUBSCRIPTION_FAILED event will notify failed payments for a subscription. The SUBSCRIPTION_CANCELED event will notify you when a subscription has been canceled.
It is possible to update the payment information for a subscription by updating it with a new transaction token.
The subscription object
| Fields | |
|---|---|
| id | string (UUID) The unique identifier for the subscription |
| store_id | string (UUID) The unique identifier for the store the charge was made to. |
| amount | number The amount to charge. |
| currency | string (ISO-4217) The currency the charge will be in. |
| amount_formatted | string The amount that was requested to be charged formatted to include a decimal place if there is a minor currency unit. |
| initial_amount | number The initial amount to charge |
| initial_amount_formatted | string The initial amount that was requested to be charged formatted to include a decimal place if there is a minor currency unit. |
| schedule_settings.start_on | string (ISO-8601) The date in which all subsequent payments should start on, in Year-Month-Day format. The date is in conjunction with the timezone declared in zone_id |
| schedule_settings.zone_id | string (IANA Timezone) The timezone the subscription will be charged at |
| schedule_settings.preserve_end_of_month | boolean If the period is month-based (e.g. monthly, bimonthly or semiannually), and the start_on date provided is the last day of the month, this option allows the charge to follow the end of the month. E.g. If start_on is 2018-06-30, then the next charge is 2018-07-31 if true and 2018-07-30 if false |
| period | string The frequency of the subscription billed. One of daily, weekly, biweekly, monthly, annually. If this field is populated, cyclical_period will not have a value |
| cyclical_period | string (ISO-8601 Duration) The frequency of the subscription expressed as a ISO-8601 duration, with a minimum frequency of 1 day and a minimum interval of 1 day. If this field is populated, period will not have a value. |
| installment_plan.plan_type | string One of none, revolving, fixed_cycles |
| installment_plan.fixed_cycles | number If plan_type is fixed_cycles, then this field is required. Specifies the number of cycles, in the installment, has to be 2 or more cyclesNumber of payments：3,5,6,10,12,15,18,20,24 |
| subscription_plan.plan_type | string One of fixed_cycles, fixed_cycle_amount |
| subscription_plan.fixed_cycles | number If subscription_plan.plan_type is fixed_cycles, then this field is required. Specifies the number of cycles, in the subscription plan |
| subscription_plan.fixed_cycle_amount | number If subscription_plan.plan_type is fixed_cycle_amount, then this field is required. Specifies the amount per cycle, in the subscription plan |
| next_payment.id | string (UUID) The unique identifier of the scheduled payment |
| next_payment.due_date | string (ISO-8601) The date this payment will be executed based on the timezone declared in zone_id. Time is fixed to 9am of the timezone declared in zone_id. |
| next_payment.zone_id | string (IANA Timezone) The timezone in which this payment will be executed at. |
| next_payment.amount | number The amount to be charged |
| next_payment.currency | string (ISO-4217) The currency to be charged in |
| next_payment.amount_formatted | string The amount to be charged formatted to include a decimal place if there is a minor currency unit. |
| next_payment.is_paid | boolean If the payment has been executed |
| next_payment.is_last_payment | boolean If this is the last payment in the subscription, only applicable for installment type subscription. |
| next_payment.created_on | string (ISO-8601) The time the scheduled payment was created on |
| payments_left | number Number of payments left, if applicable. |
| amount_left | number The amount left, if applicable. |
| amount_left_formatted | string The amount left, if applicable, formatted to include a decimal place if there is a minor currency unit. |
| status | string The status of the subscription. One of unverified, unconfirmed, canceled, unpaid, current, suspended or completed |
| metadata | json Any user defined metadata associated with the refund. |
| mode | stringlive or test. |
| created_on | string (ISO-8601) The date the refund was created on. |
| three_ds.redirect_id | string (UUID) The unique identifier for the redirect request. Will be populated if successfully set. |
| three_ds.redirect_endpoint | string (URL) The redirect endpoint when the client is returns from 3DS authentication. If not set, the user will be shown a generic completion page and asked to return manually to the originating website. |
| three_ds.mode | string The 3DS authentication mode for the charge. One of normal, required, force, skip. |