Skip to main content
Anchor to FulfillmentService

FulfillmentService

object

A Fulfillment Service is a third party warehouse that prepares and ships orders on behalf of the store owner. Fulfillment services charge a fee to package and ship items and update product inventory levels. Some well known fulfillment services with Shopify integrations include: Amazon, Shipwire, and Rakuten. When an app registers a new FulfillmentService on a store, Shopify automatically creates a Location that's associated to the fulfillment service. To learn more about fulfillment services, refer to Manage fulfillments as a fulfillment service app guide.

Mutations

You can work with the FulfillmentService object with the fulfillmentServiceCreate, fulfillmentServiceUpdate, and fulfillmentServiceDelete mutations.

Hosted endpoints

Fulfillment service providers integrate with Shopify by providing Shopify with a set of hosted endpoints that Shopify can query on certain conditions. These endpoints must have a common prefix, and this prefix should be supplied in the callbackUrl parameter in the fulfillmentServiceCreate mutation.

  • Shopify sends POST requests to the <callbackUrl>/fulfillment_order_notification endpoint to notify the fulfillment service about fulfillment requests and fulfillment cancellation requests.

    For more information, refer to Receive fulfillment requests and cancellations.

  • Shopify sends GET requests to the <callbackUrl>/fetch_tracking_numbers endpoint to retrieve tracking numbers for orders if trackingSupport is set to true.

    For more information, refer to Enable tracking support.

    Fulfillment services can also update tracking information using the fulfillmentTrackingInfoUpdate mutation, rather than waiting for Shopify to ask for tracking numbers.

  • Shopify sends GET requests to the <callbackUrl>/fetch_stock endpoint to retrieve on hand inventory levels for the fulfillment service location if inventoryManagement is set to true.

    For more information, refer to Sharing inventory levels with Shopify.

To make sure you have everything set up correctly, you can test the callbackUrl-prefixed endpoints in your development store.

Resources and webhooks

There are a variety of objects and webhooks that enable a fulfillment service to work. To exchange fulfillment information with Shopify, fulfillment services use the FulfillmentOrder, Fulfillment and Order objects and related mutations. To act on fulfillment process events that happen on the Shopify side, besides awaiting calls to callbackUrl-prefixed endpoints, fulfillment services can subscribe to the fulfillment order and order webhooks.

Anchor to FieldsFields

Anchor to callbackUrlcallbackUrl
•
URL

The callback URL that the fulfillment service has registered for requests. The following considerations apply:

  • Shopify queries the <callbackUrl>/fetch_tracking_numbers endpoint to retrieve tracking numbers for orders, if trackingSupport is set to true.
  • Shopify queries the <callbackUrl>/fetch_stock endpoint to retrieve inventory levels, if inventoryManagement is set to true.
  • Shopify uses the <callbackUrl>/fulfillment_order_notification endpoint to send fulfillment and cancellation requests.
Anchor to handlehandle
•
String!non-null

Human-readable unique identifier for this fulfillment service.

Anchor to idid
•
ID!non-null

The ID of the fulfillment service.

Anchor to inventoryManagementinventoryManagement
•
Boolean!non-null

Whether the fulfillment service tracks product inventory and provides updates to Shopify.

Anchor to locationlocation
•
Location

Location associated with the fulfillment service.

Anchor to permitsSkuSharingpermitsSkuSharing
•
Boolean!non-null

Whether the fulfillment service can stock inventory alongside other locations.

Anchor to serviceNameserviceName
•
String!non-null

The name of the fulfillment service as seen by merchants.

Anchor to trackingSupporttrackingSupport
•
Boolean!non-null

Whether the fulfillment service implemented the /fetch_tracking_numbers endpoint.

Anchor to typetype
•
FulfillmentServiceType!non-null

Type associated with the fulfillment service.

Deprecated fields

Anchor to fulfillmentOrdersOptInfulfillmentOrdersOptIn
•
Boolean!non-null

Whether the fulfillment service uses the fulfillment order based workflow for managing fulfillments.

As the migration is now finished, the fulfillmentOrdersOptIn property is deprecated and is always set to true on correctly functioning fulfillment services.

Anchor to shippingMethodsshippingMethods
•
[ShippingMethod!]!non-null

Shipping methods associated with the fulfillment service provider. Applies only to Fulfill By Amazon fulfillment service.

Was this section helpful?

Anchor to QueriesQueries

Anchor to fulfillmentServicefulfillmentService
•
query

Returns a FulfillmentService resource by ID.

Was this section helpful?

Anchor to MutationsMutations

Anchor to fulfillmentServiceCreatefulfillmentServiceCreate
•
mutation

Creates a fulfillment service.

Fulfillment service location

When creating a fulfillment service, a new location will be automatically created on the shop and will be associated with this fulfillment service. This location will be named after the fulfillment service and inherit the shop's address.

If you are using API version 2023-10 or later, and you need to specify custom attributes for the fulfillment service location (for example, to change its address to a country different from the shop's country), use the LocationEdit mutation after creating the fulfillment service.

Arguments

Anchor to callbackUrlcallbackUrl
•
URL!required

The URL to send requests for the fulfillment service. The following considerations apply:

  • Shopify queries the callback_url/fetch_tracking_numbers endpoint to retrieve tracking numbers for orders, if trackingSupport is set to true.
  • Shopify queries the callback_url/fetch_stock endpoint to retrieve inventory levels, if inventoryManagement is set to true.
  • Shopify uses the callback_url/fulfillment_order_notification endpoint to send fulfillment and cancellation requests.
Anchor to fulfillmentOrdersOptInfulfillmentOrdersOptIn
•
BooleanDefault:true

Whether the fulfillment service uses the fulfillment order based workflow for managing fulfillments.

As of 2022-07 API version, the fulfillment order based workflow is the only way to manage fulfillments. As the migration is now finished, the fulfillmentOrdersOptIn property is deprecated and is always set to true on correctly functioning fulfillment services.

The fulfillmentOrdersOptIn input field is deprecated and will be removed in the next API version. This API version makes it optional and defaults to true for a smooth migration experience. Do not set the fulfillmentOrdersOptIn argument, and you are ready for the next API version release.

Anchor to inventoryManagementinventoryManagement
•
BooleanDefault:false

Whether the fulfillment service manages product inventory and provides updates to Shopify.

Anchor to namename
•
String!required

The name of the fulfillment service.

Anchor to permitsSkuSharingpermitsSkuSharing
•
BooleanDefault:false

Whether the fulfillment service can stock inventory alongside other locations.

Anchor to trackingSupporttrackingSupport
•
BooleanDefault:false

Whether the fulfillment service provides tracking numbers for packages.

Fields

Anchor to fulfillmentServicefulfillmentService
•
FulfillmentService

The created fulfillment service.

Anchor to userErrorsuserErrors
•
[UserError!]!non-null

The list of errors that occurred from executing the mutation.

Anchor to fulfillmentServiceUpdatefulfillmentServiceUpdate
•
mutation

Updates a fulfillment service.

If you are using API version 2023-10 or later, and you need to update the location managed by the fulfillment service (for example, to change the address of a fulfillment service), use the LocationEdit mutation.

Arguments

Anchor to callbackUrlcallbackUrl
•
URL

The URL to send requests for the fulfillment service. The following considerations apply:

  • Shopify queries the callback_url/fetch_tracking_numbers endpoint to retrieve tracking numbers for orders, if trackingSupport is set to true.
  • Shopify queries the callback_url/fetch_stock endpoint to retrieve inventory levels, if inventoryManagement is set to true.
  • Shopify uses the callback_url/fulfillment_order_notification endpoint to send fulfillment and cancellation requests.
Anchor to fulfillmentOrdersOptInfulfillmentOrdersOptIn
•
Boolean

Whether the fulfillment service uses the fulfillment order based workflow for managing fulfillments.

As of 2022-07 API version, the fulfillment order based workflow is the only way to manage fulfillments, and true is the only valid value for fulfillmentOrdersOptIn.

Anchor to idid
•
ID!required

The id of the fulfillment service.

Anchor to inventoryManagementinventoryManagement
•
Boolean

Whether the fulfillment service tracks product inventory and provides updates to Shopify.

Anchor to namename
•
String

The name of the fulfillment service.

Anchor to permitsSkuSharingpermitsSkuSharing
•
Boolean

Whether the fulfillment service can stock inventory alongside other locations.

Anchor to trackingSupporttrackingSupport
•
Boolean

Whether the fulfillment service provides tracking numbers for packages.

Fields

Anchor to fulfillmentServicefulfillmentService
•
FulfillmentService

The updated fulfillment service.

Anchor to userErrorsuserErrors
•
[UserError!]!non-null

The list of errors that occurred from executing the mutation.

Was this section helpful?