Skip to main content

Manage fulfillments for prepaid subscriptions

After a prepaid subscription has been billed for, the merchant or customer might want to make changes to the subscription contract or order. For example, they might want to reschedule a shipment or refund one of the scheduled fulfillments.

This guide shows how to manage and make changes to scheduled fulfillments for prepaid subscriptions.

Anchor to RequirementsRequirements

Note
  • Most subscriptions, pre-order and try before you buy apps need to request API access through the Partner Dashboard. We give API access to apps that are designed according to our [principles for subscriptions, pre-order and TBYB apps] (/docs/apps/selling-strategies/purchase-options#shopifys-principles).
  • Public apps that use subscriptions, pre-order or TBYB need to meet specific requirements to be published on the Shopify App Store.
  • Custom apps created in the Shopify admin can't use subscriptions, pre-order or TBYB because these apps can't use extensions or request access to protected scopes. If you're building a solution for a single store, then build your custom app in the Partner Dashboard.

Anchor to Manually open a fulfillment orderManually open a fulfillment order

Merchants can opt to Fulfill early for scheduled fulfillments in the Shopify admin. For scheduled fulfillment orders, this changes the fulfillment order's status to OPEN ahead of the fulfillAt date.

Early fulfillment for prepaid subscriptions on a fulfillment order in the Shopify admin

You can also use the fulfillmentOrderOpen mutation to set a fulfillment order's status to OPEN, as demonstrated in the following example:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation {
fulfillmentOrderOpen(id: "gid://shopify/FulfillmentOrder/1899849515064") {
fulfillmentOrder {
id
status
}
userErrors {
field
message
}
}
}

JSON response

{
"data": {
"fulfillmentOrderOpen": {
"fulfillmentOrder": {
"id": "gid://shopify/FulfillmentOrder/1899849515064",
"status": "OPEN"
},
"userErrors": []
}
},
...
}

Anchor to Skip a fulfillment orderSkip a fulfillment order

A customer might want to skip a scheduled fulfillment of a product. For example, in the case of a three-month prepaid coffee subscription, a customer might decide to skip fulfillment because they already have enough coffee that month.

To skip a fulfillment order, you need to reschedule the fulfillment order and change the subscription contract's renewal date if applicable.

Anchor to Reschedule a fulfillment orderReschedule a fulfillment order

Pass a new fulfillAt date to the fulfillmentOrderReschedule mutation to reschedule a fulfillment order. In this example, the fulfillment order is rescheduled from Feb 15 to Apr 15.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation {
fulfillmentOrderReschedule(
id: "gid://shopify/FulfillmentOrder/1899851251768"
fulfillAt: "2022-04-15”
) {
fulfillmentOrder {
fulfillAt
}
userErrors {
field
message
}
}
}

JSON response

{
"data": {
"FulfillmentOrderReschedule": {
"fulfillmentOrder": {
"fulfillAt": "2022-04-15T00:00:00Z"
},
"userErrors": []
}
},
...
}

Anchor to Change the contract renewal dateChange the contract renewal date

To change the contract renewal date, you can use the subscriptionContractSetNextBillingDate mutation. Because the previous example rescheduled a fulfillment order from Feb 15 to Apr 15, the renewal date is changed to May 15 for the following example:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation {
subscriptionContractSetNextBillingDate(
contractId: "gid://shopify/SubscriptionContract/1671224"
date: "2022-05-15"
) {
contract {
nextBillingDate
}
userErrors {
field
message
}
}
}

JSON response

{
"data": {
"subscriptionContractSetNextBillingDate": {
"contract": {
"nextBillingDate": "2022-05-15T00:00:00Z"
},
"userErrors": []
}
},
...
}

Anchor to Refund a scheduled fulfillmentRefund a scheduled fulfillment

Caution

When you refund fulfillment orders, it doesn't automatically cancel the renewal that's associated with the subscription contract. To cancel the renewal, you also need to update the subscription contract.

A customer might want to refund one or more of their scheduled fulfillments. Fulfillment order cancellations and refunds are processed in reverse chronological order. You can pass the quantity to the refundCreate mutation to determine how many subscription cycles should be cancelled.

The following example cancels the last four months of a six-month prepaid subscription:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation {
refundCreate(
input: {
orderId: "gid://shopify/Order/2067697074232"
refundLineItems: {
lineItemId: "gid://shopify/LineItem/4780880232504"
quantity: 4
restockType: CANCEL
locationId: "gid://shopify/Location/9562054"
}
}
) {
refund {
id
}
userErrors {
field
message
}
}
}

JSON response

{
"data": {
"refundCreate": {
"refund": {
"id": "gid://shopify/Refund/659856"
},
"userErrors": []
}
},
...
}

Anchor to Next stepsNext steps

Was this page helpful?