All Tutorials

Manage orders for prepaid subscriptions

All Tutorials

Manage orders for prepaid subscriptions

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

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.

Fulfillment orders and subscription contracts app workflow

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

mutation {
  subscriptionContractUpdate(
    contractId: "gid://shopify/SubscriptionContract/22"
  ) {
    draft {
      id
    }
    userErrors {
      field
      message
    }
  }
}

View response

JSON response:

{
  "data": {
    "subscriptionContractUpdate": {
      "draft": {
        "id": "gid://shopify/SubscriptionContract/22"
      },
      "userErrors": []
    }
  },
  ...
}

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

mutation subscriptionDraftUpdate($draftId: ID!, $input: SubscriptionDraftInput!) {
  subscriptionDraftUpdate(draftId: $draftId, input: $input) {
    draft {
      id
    }
    userErrors {
      code
      field
      message
    }
  }
}

Input:

{
  "draftId": "gid://shopify/SubscriptionDraft/2654264",
  "input": {"deliveryMethod": {
    "shippingAddress": {
      "address1": "123 Fake Street",
      "city": "Vancouver",
      "countryCode": "CA",
      "provinceCode": "BC",
      "zip": "V6Z0A3",
      "lastName": "Doe"
                }
      }
    }
  }
}

View response

JSON response:

{
  "data": {
    "subscriptionDraftUpdate": {
      "draft": {
        "id": "gid://shopify/SubscriptionDraft/2654264"
      },
      "userErrors": []
    }
  },
  ...
}

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

mutation orderUpdate($input: OrderInput!) {
  orderUpdate(input: $input) {
    order {
      id
    }
    userErrors {
      field
      message
    }
  }
}

Input:

{
  "input": {
    "id": "gid://shopify/Order/2067697074232",
    "shippingAddress": {
      "address1": "123 Fake Street",
      "city": "Vancouver",
      "countryCode": "CA",
      "provinceCode": "BC",
      "zip": "V6Z0A3",
      "lastName": "Doe"
                }

      }
}

View response

JSON response:

{
  "data": {
    "orderUpdate": {
      "order": {
        "id": "gid://shopify/Order/2067697074232"
      },
      "userErrors": []
    }
  },
  ...
}

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

When a customer cancels a subscription order through the customer portal, apps must notify the merchant of this cancellation. If the cancellation is initiated through the app, then the app must handle the associated refunds. This applies to both prepaid and subscribe-and-save subscriptions.

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:

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

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

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 to OPEN 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).

Next steps