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
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.
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 refer to the corresponding section of the Subscriptions article.
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.