Create and manage subscription shipping rates and delivery methods

Each subscription contract has a delivery method that describes how the products in the contract will be delivered and at what price. You can update delivery methods when products are added or removed from a subscription contract.

This tutorial illustrates the calls you can make to manage shipping on subscriptions. It also provides information about the shipping rates that customers see during checkout when they buy one-time purchases or subscriptions.

Requirements

Scopes

To use the subscriptions GraphQL mutations, your app needs to request the following access scopes for a Shopify store:

  • read_own_subscription_contracts: Allow apps to read subscription contracts mutations for contracts they own.
  • write_own_subscription_contracts: Allow apps to write subscription contracts mutations for contracts they own.
  • read_shipping: Allows apps to read shipping rates.
  • write_shipping: Allows apps to write shipping rates.

Shipping rates displayed at checkout

Customers can buy one-time purchases and subscriptions when both are offered by the merchant.

When one-time purchases and subscriptions are in the same delivery profile, coming from the same location, shipping for one-time purchases is calculated with the subscription purchases. Subsequent subscription shipping rates are calculated separately. If you want to calculate subscription shipping completely separately from any one-time purchases, then you can configure a subscription-specific delivery profile. You can create a subscription-specific profile by associating a selling plan group (associated with the product) to a delivery profile using the DeliveryProfile API.

When multiple subscriptions are in the cart, shipping rates are consolidated if they share the same selling plan billing and delivery policies.

App developers need to update the shipping rate after the subscription is created.

Customers can select a shipping rate for one-time purchase products in the cart if more than one rate is available. They can also view the total cost of shipping for their subscriptions and the total cost of shipping for one-time purchases:

One-time and subscriptions shipping screenshot

Limitations

  • By default, a product will have the same shipping rate whether it's bought as a one-time purchase or as part of a subscription.
  • Pickup and local delivery methods aren't supported for subscriptions. The delivery methods also don't support one-time purchases if the cart contains a subscription.
  • Only the cheapest shipping rate is available when a product is purchased as part of a subscription. Customers can't choose between multiple shipping rates.
  • Shipping rates that are specific to a selling plan group do not display in the Shipping and delivery settings in the Shopify admin. You need to configure shipping rates for selling plan groups in your app.
  • When querying a new shipping rate for a subscription contract draft, the shipping rate returned depends on the following:
    • If the subscription contract doesn't have a selling plan ID, then the shipping rates from the delivery profile associated with the variant ID are displayed.
    • If the subscription contract doesn't have a selling plan or variant ID, then the shipping rates from the shop's general delivery profile are displayed.
  • If the rate is inherited from your delivery profile, then the rate name is "Shipping". If you define a subscription-specific rate using the API, then the specified name is used.

Specify free shipping for all subscriptions

If you don't want to charge shipping for all products in a selling plan group, then you can set a shipping rate amount of 0 for the selling plan.

In the following example, the deliveryProfileCreate mutation is used to include free shipping for all countries in the selling plan group. The sellingPlanGroupsToAssociate field represents the selling plan group IDs to be associated with the delivery profile.

Request

POST /admin/api/2021-01/graphql.json

View response

JSON response:

Restrict shipping subscriptions to specific countries

You can restrict shipping subscriptions to specific countries regardless of which shipping zones you have configured in the Shopify admin. In the following example, the selling plan group includes free shipping to the North America shipping zone.

Request

POST /admin/api/2021-01/graphql.json

View response

JSON response:

Define a flat shipping rate by country for all subscriptions

You can define a flat shipping rate per shipping zone for all subscriptions. In the following example, the selling plan group includes free shipping to Canada and specifies a $15.00 flat shipping rate for the rest of the world.

Request

POST /admin/api/2021-01/graphql.json

View response

JSON response:

Update a delivery profile with a new shipping zone

You can use to the deliveryProfileUpdate mutation to add a new shipping zone. In the following example, the "United States" shipping zone is added to the delivery profile.

Request

POST /admin/api/2021-01/graphql.json

View response

JSON response:

Request a new shipping rate for a subscription contract draft

At any time, you can query a new shipping rate for a subscription contract draft. The shippingOptions field recalculates and returns the shipping options for the subscription draft using the shop’s current shipping rates.

Fetching shipping options takes some time to execute on the backend, so you need to continuously poll on your app. The query returns one of the following statuses: success, failure or null. Sending the first request will return null. Subsequent requests will keep returning null until the job worker has succeeded or failed.

Request

POST /admin/api/2021-01/graphql.json

View response

JSON response:

Update a subscription contract with a new shipping rate

When a customer updates their subscription, any changes to shipping need to be updated in the subscription contract. You can make updates to the deliveryPrice and deliveryMethod fields in the subscriptionDraftUpdate mutation, and then commit the subscription draft to activate the changes.

Request

POST /admin/api/2021-01/graphql.json

View response

JSON response:

Webhooks

There are no webhooks specifically available for your app to receive information about shipping on subscriptions. However, the following webhooks are available if your app needs to react to a shop's delivery profile changes:

Webhook topic Description Payload
profiles/create Emitted when a delivery profile is first created. { id, }
profiles/update Emitted when a delivery profile is updated. { id, }
profiles/delete Emitted when a delivery profile is deleted. { id, }

Next steps