Manage orders for prepaid subscriptions
When an order is created by Shopify, and delivery anchors exist, the order contains delayed fulfillment orders for prepaid items. This guide describes how to keep your orders and subscription contracts in sync, and covers some common order management scenarios that relate to fulfillment orders and subscription contracts.
Keeping orders and subscription contracts in syncAnchor link to section titled "Keeping orders and subscription contracts in sync"
Changes to prepaid subscription contracts aren't automatically reflected on the associated orders. For example, when a customer updates their address for a prepaid subscription in an app, their address isn't automatically updated in the order.
The following diagram shows the required actions that your app must take to sync updates for prepaid subscription contracts:
- If the item hasn't been billed for, then update the information on the subscription contract using the
- If the item has been billed for, then update the information on the order using the
Managing cancellationsAnchor link to section titled "Managing cancellations"
The cancellation of orders doesn't automatically cancel related subscription contracts. It's recommended that apps subscribe to the
orders/cancel webhook and communicate with merchants when subscription contract orders are cancelled, so that merchants know that the subscription contract hasn't also been cancelled.
Subscription cancellation through a customer portalAnchor link to section titled "Subscription cancellation through a customer portal"
When a customer cancels a subscription order through the customer portal, apps need to notify the merchant of this cancellation. If the cancellation is initiated through the app, then the app needs to handle the associated refunds. This applies to both prepaid and subscribe-and-save subscriptions.
Order taggingAnchor link to section titled "Order tagging"
Merchants often identify and filter subscription orders in the Shopify admin. To tag orders for subscriptions from your app, you can call the
tagsAdd mutation. The following example adds tags to a specified order using the order ID:
Automatic fulfillmentAnchor link to section titled "Automatic fulfillment"
Scheduled fulfillment orders aren't eligible for automatic fulfillment. However, if a prepaid subscription order is created with its first fulfillment order set to the
OPEN state, then the fulfillment order is automatically fulfilled.
Order CSV exportAnchor link to section titled "Order CSV export"
Apps that use CSV exports to manage fulfillments can rely on the value of
lineItem.fulfillableQuantity to determine which orders are ready to fulfill. This is because
SCHEDULED fulfillment orders aren't included in the calculation of the order
For example, consider a fulfillment order scheduled to ship on January 15. Before January 15,
lineItem.fulfillableQuantity is set to 0. After January 15,
lineItem.fulfillableQuantity is set to 1. Then, after the item is fulfilled,
lineItem.fulfillableQuantity is set back to 0.
Order webhooksAnchor link to section titled "Order webhooks"
Your app can subscribe to order webhooks that are useful for apps that manage fulfillment orders for merchants. The following examples show the JSON responses from each of the available webhooks.
To learn how to set up and consume webhooks, refer to Webhooks configuration.
- Learn about fulfillments for prepaid subscriptions.