Fulfillment for prepaid subscriptions

• Your app can make authenticated requests to the GraphQL Admin API.

• Your app has the merchant_managed_fulfillment_orders and third_party_fulfillment_orders access scopes. Learn how to configure your access scopes using Shopify CLI.

• You're familiar with selling plans, subscription contracts, and the use and setup of delivery anchors.

• You're familiar with managing fulfillments as an order management app.

When a customer purchases a prepaid subscription from a merchant, a subscription contract and an order are created. The order contains multiple fulfillment orders which are scheduled to be fulfilled at a later time. This enables support for prepaid subscription scenarios, where a customer wants to pay up front for a product that's delivered using billing and delivery intervals.

The scheduled fulfillment dates on the fulfillment orders are determined based on the delivery anchors that are set up on the selling plan's sellingPlanRecurringDeliveryPolicy, as well as the originTime that's provided during subsequent billing attempts.

The follow image describes an example lifecycle for a prepaid subscription:

1. The customer begins checkout. The checkout line item is a three-month prepaid subscription of coffee bags and the quantity is one.
2. The customer completes the checkout. Both a subscription contract and an order are created. The order line item is coffee bags and the quantity is three.
3. Three fulfillment orders in a SCHEDULED state are created and associated with the order. The fulfillment orders have the following fulfillAt dates:
   • Fulfillment order 1: Jan 15
   • Fulfillment order 2: Feb 15
   • Fulfillment order 3: Mar 15

When the fulfillAt date for each fulfillment order is reached, inventory is committed and the fulfillment order is transitioned to the OPEN state, marking the items in that fulfillment order as fulfillable.

On Jan 15, the first fulfillment order transitions to an OPEN state, indicating that fulfillment should begin for the item. Only the items that are meant to be fulfilled on January 15 are ready for fulfillment, whereas the remaining items are shown as scheduled:

A subscription appears as one line item on the checkout. However, the line item quantity on the corresponding order represents the interval count of the subscription billing policy. For example, if a customer buys a three-month subscription of coffee beans, then the checkout line item quantity is 1 and order line item quantity is 3.

The fulfillAt attribute of a fulfillment order represents when the merchant should start fulfilling the items in the fulfillment order. The attribute also contributes to the grouping of line items for fulfillment orders with the SCHEDULED status, along with location, fulfillment service, delivery method, and delivery profile.

For fulfillment orders that are assigned to a third-party fulfillment service, the fulfillAt attribute represents when the merchant should request fulfillment from the fulfillment service.

The SCHEDULED status of fulfillmentOrderStatus represents the state of fulfillment orders that are created with a future fulfillAt date. The order's displayFulfillmentStatus is SCHEDULED only when all associated fulfillment orders are in a SCHEDULED state.

When a pre-paid subscription contract is up for renewal, apps need to trigger a billing attempt using the subscriptionBillingAttemptCreate mutation. The customer is then billed and a new order is generated for the new billing cycles.

A customer might request a refund for one or more scheduled fulfillments. Refunds are supported in the Shopify admin, but you can also support a variety of refund scenarios using the refundCreate mutation.

Refunds are made starting on the last scheduled fulfillment and then working backwards in reverse chronological order.

Fulfillment orders with SCHEDULED status are prioritized over those with OPEN status. The fulfillment orders are selected for refund using the value of fulfillAt in descending order.

Refer to the Manage fulfillments for prepaid subscriptions tutorial for an example of how refunds apply to scheduled fulfillments.

You can subscribe to the refunds/create webhook in case the merchant does a refund on a prepaid subscription order through the Shopify admin or another app. In these scenarios, you can use the webhook as a trigger to communicate with the merchant that they might want to also cancel the associated subscription contract.

Customers might add a combination of prepaid subscriptions, subscribe-and-save subscriptions, and non-subscription (one-time purchase) items to their cart. This section describes how fulfillment orders are created for some example scenarios.

For these example scenarios, the test shop has only one location, one manual fulfillment service, one delivery profile, and one delivery method.

A customer might add multiple prepaid subscription items to their order.

In this example, a customer orders the following items on Jan 10:

• A three-month prepaid subscription for coffee filters
• A three-month prepaid subscription for coffee bags

If the subscriptions have different anchor dates, then the order is created with separate fulfillment orders for each line item. The following image shows the fulfillment orders for subscriptions with different anchor dates on the 15th and 17th of each month:

If the subscriptions share the same anchor date, then the fulfillment orders are combined for each billing cycle. The following image shows the fulfillment orders for each subscription with shared anchor dates on the 15th of each month:

A customer might purchase a prepaid subscription item with a non-subscription (one-time purchase) item at the same time. The resulting order contains both of the purchased items.

In this example, the customer orders the following items on Jan 10:

• A three-month prepaid subscription for coffee bags
• A one-time purchase for a Seiko Coffee Machine

Because the Seiko Coffee Machine can be fulfilled immediately, four fulfillment orders are generated:

However, if the customer orders these items on the anchor date, then the one-time purchase is added to the same fulfillment order as the first cycle for the prepaid subscription. The following image shows that only three fulfillment orders are generated for this scenario:

A customer might purchase a prepaid subscription item with a subscribe-and-save subscription item at the same time. This creates two subscription contracts: one for the prepaid subscription and one for the subscribe-and-save subscription.

The first generated order includes all cycles of the prepaid item and only the first cycle of the subscribe-and-save item.

In this example, the customer orders the following items on Jan 10:

• A three-month prepaid subscription for coffee bags with an anchor date on the 15th of each month
• A subscribe-and-save subscription for coffee filters with billing and fulfillment anchor dates on the 12th of each month

The first order with ID 444 is generated on Jan 10 and has the following fulfillment orders:

The statuses on these fulfillment orders change on the anchor dates. The following diagram shows when the fulfillment status changes and inventory is committed for this first order:

On Feb 15, the fulfillment order for coffee bags on the prepaid subscription for the first order transitions to an OPEN status.

On Feb 12, a new order with ID 555 is generated for the subscribe-and-save subscription after a successful billing attempt. The inventory is committed upon order creation and the fulfillment order is created with an OPEN status.

In API version 2023-01 and higher, your app can subscribe to webhooks for event notifications related to fulfillment orders. 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 overview.

For mobile clients (version 8.75.0 or older), scheduled fulfillment orders are hidden from the mobile UI. After a scheduled fulfillment order’s fulfillAt date expires and it transitions to an OPEN state, it becomes visible in the UI.

This means that scheduled fulfillment orders can't be manually marked as OPEN in advance of their fulfillAt date on legacy mobile clients.

POS Classic (Android & iOS) doesn't show the fulfillment statuses of scheduled orders.

For the all-new POS (iOS version 6.19 and older), fulfillment status isn't exposed for scheduled orders. Products that are sold as subscription-only aren't displayed in the product catalogue on POS. If an app adds a subscription-only product to the cart, then an error is raised.

• Learn how to manage fulfillments for prepaid subscriptions, including how to manually open fulfillment orders, skip and reschedule fulfillment orders, and refund scheduled fulfillments.
• Learn how to manage orders for prepaid subscriptions by keeping subscription contract and order information in sync.