How to customize the next subscription occurrences
Problem
You have generated one or more subscriptions from a source order, based on the subscription model configuration. At some point, you may want to suspend some of them, re-activate them, or even change the next subscription occurrences in terms of frequency, items, expiration date, and more.
Solution
Once generated, automatic order subscriptions live a life of their own, meaning that any changes to the associated subscription model or source order won't affect the already generated order subscriptions and will eventually apply starting from the next subscription generation only.
To update an already generated subscription you need to edit the order subscription itself or the related order subscription items. You can do it any time in between each run.
Updating the order subscription
Suspending, activating, and cancelling an order subscription
Active order subscriptions can be deactivated (temporarily suspended) and eventually re-activated, or cancelled.
Deactivate
To deactivate an order subscription, send a PATCH request to the /api/order_subscriptions/:id setting the _deactivate trigger attribute to true:
The following request deactivates the subscription identified by the "BkMdJFGdjX" ID:
When reactivating an inactive order subscription the next run date could be automatically recomputed to avoid date inconsistencies (e.g. a next occurrence scheduled at a time when the subscription was inactive, in which case is set to be equal to the order subscription's updated_at — i.e. the next run happens as soon as the subscription is reactivated). If needed, you can still update the next_run_at value when passing the _activate trigger attribute to set the next run at the desired date.
Cancel
To cancel an order subscription, send a PATCH request to the /api/order_subscriptions/:id setting the _cancel trigger attribute to true:
The following request cancels the subscription identified by the "mPbnqFvRPN" ID:
When changing the frequency of an already generated subscription the next run date is not re-computed. That's why we strongly recommend passing also the next_run_at attribute to set the new desired next run date accordingly and avoid possible date inconsistencies (e.g. if you change a subscription frequency from yearly to weekly without setting the next_run_at attribute, the next occurrence will happen next year and not next week as probably expected).
Changing the subscription expiration date
Adding an expiration date to an order subscription is optional. To set or change the expiration date of an order subscription, send a PATCH request to the /api/order_subscriptions/:id setting the expires_at attribute:
The following request changes the expiration date of the subscription identified by the "BkMdJFGdjX" ID:
Expired subscription, if still in the active status, can be resumed by moving the expiration date to a future time. In this case, the next run date could be automatically recomputed to avoid date inconsistencies (with the same logic as in the case of a subscription reactivation).
Changing the subscription next run date
To update an order subscription's next occurrence date, send a PATCH request to the /api/order_subscriptions/:id setting the next_run_at attribute:
The following request changes the next occurrence date of the subscription identified by the "BkMdJFGdjX" ID:
The new value for the next_run_at attribute can't be before the moment of the update. Once changed the next run, the subsequent occurrences will be scheduled from the new next_run_at value, based on the order subscription frequency.
Changing the customer payment source
The recurring orders associated to a subscription are placed using the saved customer payment source (if still valid). If you need or want to update it, send a PATCH request to the /api/order_subscriptions/:id setting the customer_payment_source relationship:
The following request associates the customer payment source identified by the "OvEOysMVAD" ID with the order subscription identified by the "BkMdJFGdjX" ID:
The new payment source must be one of the available payment sources for the customer (saved in their customer wallet).
Updating the order subscription items
To avoid any possible issue or date inconsistency (especially in the case of high-frequency subscriptions) we suggest deactivating the order subscription before making any changes to the associated order subscription items and reactivating it right after.
Changing the quantity of a product belonging to a subscription
To change the quantity of a product belonging to a subscription, send a PATCH request to the /api/order_subscriptions_item/:id setting the quantity attribute:
The following request updates the quantity of the order subscription items identified by the "adkLKwFVzG" ID:
Changing the price of a product belonging to a subscription
To change the unit price of a product belonging to a subscription, send a PATCH request to the /api/order_subscriptions_item/:id setting the unit_amount_cents attribute:
The following request updates the unit price of the order subscription items identified by the "adkLKwFVzG" ID:
Changing the price of a product belonging to an ongoing subscription overrides the original source order line item price (even if computed from a price tier). The new price will be used for all the next subscription occurrences until further updates.
Changing one of the subscription products
To change one of the products belonging to a subscription, send a PATCH request to the /api/order_subscriptions_item/:id setting the sku_code or bundle_code attribute:
The following request changes the SKU code of the order subscription items identified by the "adkLKwFVzG" ID:
If you simply update the SKU code without nullifying the unit amount you're just changing the product in the subscription, keeping the price of the old one. Setting the unit_amount_cents to null guarantees that the price is recomputed using the price associated with that product in that market (price tiers, if any, are honored as well). The other option is to manually set the desired price at the moment of the update.
Adding a new product to a subscription
To manually add a new product to an already generated subscription you just need to create a new order subscription item. To do that, send a POST request to the /api/subscription_items endpoint specifying the quantity attribute and setting the order_subscription and item relationships:
The following request creates a new order subscription item from the item identified by the "nJoqSzPEAq" ID and associates it with the order subscription identified by the "DPAwmFnYkJ" ID:
Being part of an order subscription, the allowed item types are skus, bundles, and adjustments only.
On success, the API responds with a 201 Created status code, returning the newly created order subscription item object (since the unit price wasn't specified in the request, it is inherited from the item):
To manually remove a product from an already generated subscription you just need to delete the related order subscription item. To do that, send a DELETE request /api/subscription_items/:id endpoint:
The following request deletes the order subscription item identified by the "ydzZAyFpNb" ID:
