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.

Subscriptions are charged periodically based on the time period specified on creation. They are cancellable at any time. If a charge fails on a subscription, it will be retried the following day. If a subscription has specific number of consecutive failed charges, it will automatically be cancelled.

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. If you update an unpaid subscription’s transaction token, it will immediately create another charge.

The subscription object

Fields
idstring (UUID)
The unique identifier for the subscription
store_idstring (UUID)
The unique identifier for the store the charge was made to.
amountnumber
The amount to charge.
currencystring (ISO-4217)
The currency the charge will be in.
amount_formattedstring
The amount that was requested to be charged formatted to include a decimal place if there is a minor currency unit.
initial_amountnumber
The initial amount to charge
initial_amount_formattedstring
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_onstring (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_idstring (IANA Timezone)
The timezone the subscription will be charged at
schedule_settings.preserve_end_of_monthboolean
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
periodstring
How frequently the subscription is billed. One of daily, weekly, biweekly, monthly, annually
installment_plan.plan_typestring
One of none, revolving, fixed_cycles, fixed_cycle_amount
installment_plan.fixed_cyclesnumber
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 cycles
Number of payments:3,5,6,10,12,15,18,20,24
installment_plan.fixed_cycle_amountnumber
If plan_type is fixed_cycle_amount, then this field is required. Specifies the amount per cycle, in the installment
next_payment.idstring (UUID)
The unique identifier of the scheduled payment
next_payment.due_datestring (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_idstring (IANA Timezone)
The timezone in which this payment will be executed at.
next_payment.amountnumber
The amount to be charged
next_payment.currencystring (ISO-4217)
The currency to be charged in
next_payment.amount_formattedstring
The amount to be charged formatted to include a decimal place if there is a minor currency unit.
next_payment.is_paidboolean
If the payment has been executed
next_payment.is_last_paymentboolean
If this is the last payment in the subscription, only applicable for installment type subscription.
next_payment.created_onstring (ISO-8601)
The time the scheduled payment was created on
payments_leftnumber
Number of payments left, if applicable.
amount_leftnumber
The amount left, if applicable.
amount_left_formattedstring
The amount left, if applicable, formatted to include a decimal place if there is a minor currency unit.
statusstring
The status of the subscription. One of unverified, unconfirmed, canceled, unpaid, current, suspended or completed
metadatajson
Any user defined metadata associated with the refund.
modestring
live or test.
created_onstring (ISO-8601)
The date the refund was created on.