Create a Subscription

POST /subscriptionsplans/v1/plans/plan_id/subscriptions

Once you have created a plan, you can then create a subscription based on that plan in order to schedule recurring payments for a consumer.

Note the following:

  • The plan you use (referenced by the plan_id in the endpoint above) must have a status of ACTIVE.
  • If the plan endDate has passed, the plan will have the status of EXPIRED and can no longer be used to create a subscription.

To create a subscription, you must initiate a POST request to the subscriptions endpoint.

Before trying the example, you should:

  • Replace the plan ID (e067d83f-add7-4b6b-8884-dfa8693dde1f) with the id you received in the response to your plan creation request.
  • Replace the API key (after the -u) with the Test API key you have received.
  • Replace the paymentToken (CNjEzMTM4NDg1) with a payment token you have created with the Customer Vault API in the Test environment.

This table describes the elements used in a subscription creation request.

Element Type Required Description
accountId string Yes

This is the merchant account that is used to process the payments in this subscription.

Note that the processing currency of the merchant account must be the same as the plan's currency, except if it is a load balancing master account.

paymentToken string Yes This is the card payment token or the bank account payment token to be used for billing the consumer.
paymentDescriptor number This is a descriptor that will appear on the consumer's credit card or bank account statement.
merchantRefNum string Yes This is the merchant reference number, an identifier created by the merchant and submitted as part of the request.


This validates that this request is not a duplicate. A request is considered a duplicate if the merchantRefNum has already been used in a previous request within the past 90 days. Default = true.



This is the number of items in the subscription. E.g., if set to 2, the consumer would be charged two times the amount value specified in the plan at each billing period.

status enum

This is the status of the subscription that was created. Possible values are:

  • ACTIVE – The subscription is generating regular billings.
  • CANCELLED – The subscription has been cancelled, so no billings are generated.
  • EXPIRED – The subscription has reached the end date.
  • PAST_DUE – One or more payment attempts have failed and re-attempt(s) have been scheduled; scheduled billings are still being generated.
  • SUSPENDED – The subscription is temporarily not generating billings.
startDate string

This is the date the subscription starts. Note: This defaults to the current date.


endDate string

This is the date the subscription ends. Note: If not provided, the subscription will continue indefinitely.


The response contains the following elements, in addition to those described in the table above.

Element Type Description
id string This is the unique subscription ID returned in the response.
creationTime UTC formatted date

This is the date and time the subscription was created.

lastUpdatedTime UTC formatted date This is the date and time the subscription was last updated.



This is the date the billing period starts.




This is the date the billing period ends.

links array of link objects

This contains a self link that can be used to fetch details about the request.

_expandable object

This displays expandable resources for the plan used and the profile from which the paymentToken was taken.

For a complete list and description of the elements and values associated with a subscription, consult the subscription creation API request.

Did you find this page useful?