This article applies to Contextual Commerce. (Looking for Classic Commerce documentation?)
All API endpoints work with subscription instances which are represented by unique identifiers. Those identifiers can be obtained by subscribing to Webhooks or by requesting all subscriptions using GET /subscriptions.
Get All Subscription Instances
Get One or More Subscription Instances
Look Up Subscriptions by Parameters
You can append one or more parameters the URL to filter the results in a variety of ways. The first parameter should be appended using a question mark (?); use an ampersand (&) for any subsequent parameters.
|begin||date||specify the beginning of a date range in yyyy-mm-dd-format|
|end||date||specify the end of a date range in yyyy-mm-dd format|
|event||canceled||use with begin and end to retrieve subscriptions that were canceled within a given date range|
|charged||use with begin and end to retrieve subscriptions that were charged within a given date range; specify a future date range to retrieve subscriptions with upcoming charges|
|created||use with begin and end to retrieve subscriptions that were created within a given date range|
|deactivated||use with begin and end to retrieve subscriptions that were deactivated within a given date range|
|trialended||use with begin and end to retrieve subscriptions for which the trial period ended within a given date range|
|trialstarted||use with begin and end to retrieve subscriptions for which the trial period began within a given date range|
|products||product ids||enter one or more product ids to filter the response to include only subscriptions for the specified products; use commas to separate multiple values|
|scope||all||*scope=all is unnecessary; if no scope parameter is passed, the API will return both live and trial subscriptions by default|
|live||specify scope=live to retrieve only live (non-trial) subscriptions|
|trial||specify scope=trial to retrieve only trial (non-live) subscriptions|
|status||active||specify status=active to retrieve only subscriptions that are currently active (note: this includes subscriptions with free trial days that are still in trial status)|
|canceled||specify status=canceled to retrieve only subscriptions that have been canceled but not yet deactivated|
|deactivated||specify status=deactivated to retrieve only subscriptions that have been deactivated|
|overdue||specify status=overdue to retrieve only subscriptions that are currently overdue due to a failed rebill charge|
|trial||specify status=trial to retrieve only subscriptions that are currently in trial status (i.e. via the Free Trial Days feature of the subscription product's pricing configuration)|
Get Subscription Instance Entries
Returns an array of order objects, one for each transaction associated with the specified subscription ID. This includes the original order by which the subscription was created, all subscription billings, and any transactions resulting from prorated subscription edits. To identify the original order, you can either identify the object with the earliest changed date, or identify the object for which the order.reference does not include a "B" at the end of the string (the "B" denotes a subscription billing).
Update Existing Subscription Instances
If you change the product on an active subscription to a different subscription product via the API:
- Any free trial period associated with the new product will be ignored. In case you need to change the product on a subscription and have the new product's free trial period take effect, you can make this change via the Dashboard under the Activity menu.
- The product price of the new product will be used for future billings. In case you need to change the product on a subscription and have the original product's price remain in effect, you can also pass the optional pricing info as shown in the third example below.
- If the product price of the new product is greater than the price of the original product, the change will be recorded as an upgrade. If the price of the new product is less than the original product, the change will be recorded as a downgrade.
- If you pass "prorate": true on a subscription change and the automatic prorated billing is declined or fails, the subscription will still be updated successfully. The subscription.charge.failed webhook event - and the associated customer-facing email message - will be fired and the subscription will go into an overdue state.
- For more information about proration with subscription upgrades and downgrades, please see Prorating When Upgrading Or Downgrading Subscription Plans.
- If you want to apply a custom identifier to a subscription instance, to be included in future webhook events and / or for use in making a GET request to /subscriptions, you can pass "customReferenceId":"<yourvalue>".
Important: Changing a subscription instance from automatic to manual renewal results in the payment method associated with the subscription being permanently deleted. This cannot be undone. Going forward, the customer will need to log on to account management and make payments manually prior to the next billing date in order to prevent the subscription from being canceled due to non-payment. If a customer has multiple subscriptions, subscriptions other than the one(s) associated with the ID specified in the body of your POST will not be affected.
Cancel Subscription Instances
Cancel after the current period is ended (default behavior).
Uncancel a Canceled Subscription Instance Prior to Deactivation
If you need to reverse or undo the cancelation of a subscription instance prior to the subscription's deactivation, you can uncancel the subscription instance by passing in "deactivation": null. However, if the subscription has already reached its deactivation date, it cannot be uncanceled.
You can also pass other values in the same uncancel request.
Rebill "Managed" Subscription Instances
To learn more about managed subscriptions, please see our article Managed Subscriptions and Usage-Based Billing.
If you would like to change rebill amount or subscription contents you will need to update the subscription instance first by using the corresponding operation above.