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 tutorial covers some common order management scenarios that relate to fulfillment orders and subscription contracts.
Keeping orders and subscription contracts in sync
Anchor 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. To support this use case, you need to make calls to SubscriptionContractUpdate and subscriptionDraftUpdate to update the delivery method address on the contract. You also need to call OrderUpdate to update the shipping address on the order.
Updating the subscription contract
Anchor link to section titled "Updating the subscription contract"Before you can update the subscription draft, you need to get a draft ID.
Use the subscriptionContractUpdate
mutation and supply the subscription contract ID. The response includes a draft ID.
Example request:
POST /admin/api/2021-01/graphql.json
View response
JSON response:
Updating the subscription draft
Anchor link to section titled "Updating the subscription draft"You can call the subscriptionDraftUpdate
mutation to make changes to a subscription draft. In the following example, the delivery method address is changed.
Example request
POST /admin/api/2021-01/graphql.json
Input:
View response
JSON response:
Updating the order
Anchor link to section titled "Updating the order"You can call the OrderUpdate mutation to make changes to a order. The following example updates the order to include a shipping address.
Example request
POST /admin/api/2021-01/graphql.json
Input:
View response
JSON response:
Managing cancellations
Anchor link to section titled "Managing cancellations"The cancellation of orders related to subscription contracts doesn't automatically cancel these 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 portal
Anchor 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 tagging
Anchor 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 use the /orders
endpoint in REST or send a GraphQL Order mutation. The following example adds tags to a specific order using the order ID:
PUT https://{shop}.myshopify.com/admin/api/2022-04/orders/{order_id}.json
View response
API response:
Input:
View response
JSON response:
Automatic fulfillment
Anchor 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.
In the Set the cutoff date for a selling plan example, the customer checks out on January 8 with an item from a selling plan that has its pre-anchor behaviour set to ASAP
. The first fulfillment order (with the fulfillAt
date of Jan 8) is then fulfilled right away.
Order CSV export
Anchor 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 lineItem.fulfillableQuantity
.
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 webhooks
Anchor link to section titled "Order webhooks"The following webhooks are useful for apps that manage fulfillment orders for merchants:
orders/create
- Get notified when an order is created. Apps will need to check the line items and their selling plan application to determine whether this is a subscription order that they own.orders/updated
- Get notified when an order with a subscription contract is updated, or when the scheduled fulfillment order is transitioned toOPEN
state. For example, this could be important for address updates.orders/cancelled
- Get notified when an order is cancelled. This can be useful for apps to ensure contracts get cancelled as well (if that's the merchants intention).refunds/create
- Get notified when a refund is created. This can be useful for apps to ensure contracts get updated as well (if that's the merchants intention).
- Create and manage fulfillments for prepaid subscriptions: Learn the calls you can make to manage fulfillments on subscriptions.
- Handling advanced scenarios for subscription-based fulfillment orders: Learn the calls you can make to manage advanced fulfillment scenarios for subscriptions.