Handling advanced scenarios for subscription-based fulfillment orders

This tutorial illustrates the calls you can make to manage advanced fulfillment scenarios for subscriptions. It provides information about the following:

Requirements

Example scenario for this tutorial

Using the subscription APIs, you can create a recurring three-month prepaid subscription of coffee bags. In this scenario, three separate fulfillment orders are created for the order. The test shop assumed in this scenario has the following setup:

Multiple Prepaid subscriptions

Customers can add multiple prepaid subscription items to an order.

In the following example, the customer orders the following items on January 10th:

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

The items are both in different selling plans, and the coffee bags fulfillment begins on the 15th of every month, while the filters begin on the 17th.

API request

Input for coffee bags

Input for coffee filters

View response

JSON response:

The API calls result in the following fulfillment orders, when the associated product is purchased:

Multiple prepaid subscriptions

Combining fulfillment orders

If two items in different fulfillment orders share the same anchor date, then they'll be combined into one fulfillment order for each cycle. For example, if both items have an anchor date of the 15th day of the month, then this results in three fulfillment orders with both items (one for each month).

Combining fulfillment orders

Prepaid subscription with non-subscription items

Customers can purchase a prepaid subscription item with a regular one-off (non-subscription) item at the same time. The order that gets generated contains both of the items purchased.

In addition to the three-month coffee bags prepaid subscription in the API example, the customer also adds a Seiko espresso machine and completes the checkout process on January 10. Because the Seiko is a one-off and can be fulfilled right away, four fulfillment orders are generated:

Non subscription items

However, if the cutoff date is removed on the delivery policy and the order is placed on the 15th, then three fulfillment orders are generated. The first fulfillment order includes both items:

Non subscription items no cutoff

Prepaid subscription with subscribe-and-save subscription items

Customers can 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 item and one for the regular pay-per-delivery subscription. The first order generated includes all cycles of the prepaid item, and the first cycle of the subscribe-and-save item.

In the following example, the customer buys a three month coffee bag subscription, as well as a pay-per-delivery subscription of coffee filters. The checkout is completed on January 10. The coffee filters selling plan is set up so that its items are billed and fulfilled monthly on the 12th with no cutoff defined.

The first order (ID 444) would have the following fulfillment orders:

Prepaid subscription with pay-per-delivery subscription items

Input for the prepaid subscription

Subscribe and save example

The following example includes the API call that adds a subscribe-and-save subscription for coffee filters for the 12th of each month:

Request

POST /admin/api/unstable/graphql.json

View response

JSON response:

There are two fulfillment orders in January, one for the coffee filters and one for the coffee bags. The following diagram shows inventory being committed on the 12th for the coffee filters and on the 15th for the coffee bags:

Prepaid subscription with pay-per-delivery subscription items

On February 15, the fulfillment order for the coffee bags transition to OPEN. In addition, a new order (ID 555) is generated after success of the billing attempt for the pay-per-delivery subscription of coffee filters.

Order ID 555 is a new order created on February 12. The inventory is committed upon order creation and the fulfillment order is created in an OPEN state.

Prepaid subscription with pay-per-delivery subscription items

Next steps