Skip to main content

The REST Admin API is a legacy API as of October 1, 2024. Starting April 1, 2025, all new public apps must be built exclusively with the GraphQL Admin API. For details and migration steps, visit our migration guide.

FulfillmentService

Requires fulfillments access scope.

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.

Using the FulfillmentService resource, you can register, edit, and delete a new fulfillment service.

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 callback_url parameter in the request that creates the fulfillment service.

  • Shopify sends POST requests to the callback_url/fulfillment_order_notification endpoint to notify the fulfillment service about fulfillment requests and fulfillment cancellation requests.
    As of the 2022-07 API version, it's mandatory for a fulfillment service to follow a fulfillment order based workflow by hosting the callback_url/fulfillment_order_notification endpoint, and acting on fulfillment requests and cancellations.
    For more information, refer to Receive fulfillment requests and cancellations.
  • Shopify sends GET requests to the callback_url/fetch_tracking_numbers endpoint to retrieve tracking numbers for orders if tracking_support is set to true.
    For more information, refer to Enable tracking support.
    Fulfillment services can also update tracking information with a corresponding API, rather than waiting for Shopify to ask for tracking numbers.
  • Shopify sends GET requests to the callback_url/fetch_stock endpoint to retrieve on hand inventory levels for the fulfillment service location if inventory_management 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 callback_url-prefixed endpoints in your development store.

Resources and webhooks

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

Was this section helpful?
#

Endpoints

Anchor to

The FulfillmentService resource

Anchor to

Properties

admin_graphql_api_id
->
id

The GraphQL GID for this fulfillment service.

callback_url
->
callbackUrl

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

Show callback_url properties
  • Shopify queries the callback_url/fetch_tracking_numbers endpoint to retrieve tracking numbers for orders, if tracking_support is set to true.
  • Shopify queries the callback_url/fetch_stock endpoint to retrieve inventory levels, if inventory_management is set to true.
  • Shopify uses the callback_url/fulfillment_order_notification endpoint to send fulfillment and cancellation requests
fulfillment_orders_opt_in
deprecated

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 fulfillment_orders_opt_in must be set to true.
As the migration is now finished, the fulfillment_orders_opt_in property is deprecated and is always set to true on correctly functioning fulfillment services.

permits_sku_sharing
->
permitsSkuSharing

Whether the fulfillment service can stock inventory alongside other locations.

handle
->
handle

Human-readable unique identifier for this fulfillment service.

inventory_management
->
inventoryManagement

Whether the fulfillment service tracks product inventory and provides updates to Shopify. Valid values: true and false.

location_id
->
id

The unique identifier of the location associated with the fulfillment service

name
->
serviceName

The name of the fulfillment service as seen by merchants.

provider_id
deprecated

A unique identifier for the fulfillment service provider.

requires_shipping_method
deprecated

Whether the fulfillment service requires products to be physically shipped. Valid values: true and false.

tracking_support
->
trackingSupport

Whether the fulfillment service provides tracking numbers for packages. Valid values: true and false.

Was this section helpful?
{}

The FulfillmentService resource

{
"admin_graphql_api_id": "gid://shopify/FulfillmentService/1",
"callback_url": "http://myapp.com",
"fulfillment_orders_opt_in": true,
"permits_sku_sharing": true,
"handle": "my-fulfillment-service",
"inventory_management": true,
"location_id": 19,
"name": "My Fulfillment Service",
"provider_id": null,
"requires_shipping_method": true,
"tracking_support": true
}

Anchor to POST request, Create a new FulfillmentService
post
Create a new FulfillmentService

fulfillmentServiceCreate

Anchor to Parameters of Create a new FulfillmentServiceParameters

api_version
string
required
callback_url

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

Show callback_url properties
  • Shopify queries the callback_url/fetch_tracking_numbers endpoint to retrieve tracking numbers for orders, if tracking_support is set to true.
  • Shopify queries the callback_url/fetch_stock endpoint to retrieve inventory levels, if inventory_management is set to true.
  • Shopify uses the callback_url/fulfillment_order_notification endpoint to send fulfillment and cancellation requests
fulfillment_orders_opt_in
boolean
default true

Whether the fulfillment service uses the fulfillment order based workflow for managing fulfillments.
As the migration is now finished, the fulfillment_orders_opt_in property is deprecated and will be removed in the next API version. This API version defaults it to true for a smooth migration experience. Do not set the fulfillment_orders_opt_in argument, and you are ready for the next API version release.

inventory_management
boolean

Whether the fulfillment service tracks product inventory and provides updates to Shopify. Valid values: true and false.

name
string

The name of the fulfillment service as seen by merchants.

permits_sku_sharing
boolean
default false

Whether the fulfillment service can stock inventory alongside other locations.

requires_shipping_method
boolean

Whether the fulfillment service requires products to be physically shipped. Valid values: true and false.

tracking_support
boolean

Whether the fulfillment service provides tracking numbers for packages. Valid values: true and false.

Was this section helpful?

Anchor to post-fulfillment-services-examplesExamples

Create a fulfillment service

Request body
fulfillment_service
Fulfillment_service resource
Show fulfillment_service properties
fulfillment_service.name:"Jupiter Fulfillment"

The name of the fulfillment service as seen by merchants.

fulfillment_service.callback_url:"http://google.com"

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

Show callback_url properties
  • Shopify queries the callback_url/fetch_tracking_numbers endpoint to retrieve tracking numbers for orders, if tracking_support is set to true.
  • Shopify queries the callback_url/fetch_stock endpoint to retrieve inventory levels, if inventory_management is set to true.
  • Shopify uses the callback_url/fulfillment_order_notification endpoint to send fulfillment and cancellation requests
fulfillment_service.inventory_management:true

Whether the fulfillment service tracks product inventory and provides updates to Shopify. Valid values: true and false.

fulfillment_service.tracking_support:true

Whether the fulfillment service provides tracking numbers for packages. Valid values: true and false.

fulfillment_service.permits_sku_sharing:true

Whether the fulfillment service can stock inventory alongside other locations.

Was this section helpful?
post

/admin/api/2025-07/fulfillment_services.json

curl -d '{"fulfillment_service":{"name":"Jupiter Fulfillment","callback_url":"http://google.com","inventory_management":true,"tracking_support":true,"permits_sku_sharing":true}}' \
-X POST "https://your-development-store.myshopify.com/admin/api/2025-07/fulfillment_services.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"

{}

Response

JSON
HTTP/1.1 201 Created
{
"fulfillment_service": {
"id": 1061774488,
"name": "Jupiter Fulfillment",
"email": null,
"service_name": "Jupiter Fulfillment",
"handle": "jupiter-fulfillment",
"fulfillment_orders_opt_in": true,
"include_pending_stock": false,
"provider_id": null,
"location_id": 1072404543,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true,
"admin_graphql_api_id": "gid://shopify/ApiFulfillmentService/1061774488",
"permits_sku_sharing": true,
"requires_shipping_method": true
}
}

Anchor to GET request, Receive a list of all FulfillmentServices
get
Receive a list of all FulfillmentServices

shop

Anchor to Parameters of Receive a list of all FulfillmentServicesParameters

api_version
string
required
scope
enum

Specify which fulfillment services to retrieve.

Show scope properties

  • current_client: Returns fulfillment providers that have been created by the app sending the request (default)

  • all: Returns all the fulfillment providers

Was this section helpful?

Anchor to get-fulfillment-services?scope=all-examplesExamples

List all of the shop's fulfillment services

Query parameters
scope=all
enum

Specify which fulfillment services to retrieve.

Show scope properties

  • current_client: Returns fulfillment providers that have been created by the app sending the request (default)

  • all: Returns all the fulfillment providers

List your app's fulfillment services

Was this section helpful?
get

/admin/api/2025-07/fulfillment_services.json?scope=all

curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-07/fulfillment_services.json?scope=all" \
-H "X-Shopify-Access-Token: {access_token}"

{}

Response

JSON
HTTP/1.1 200 OK
{
"fulfillment_services": [
{
"id": 611870435,
"name": "Venus Fulfillment",
"email": null,
"service_name": "Venus Fulfillment",
"handle": "venus-fulfillment",
"fulfillment_orders_opt_in": true,
"include_pending_stock": false,
"provider_id": null,
"location_id": 611870435,
"callback_url": "http://google.com/",
"tracking_support": false,
"inventory_management": false,
"admin_graphql_api_id": "gid://shopify/ApiFulfillmentService/611870435",
"permits_sku_sharing": false,
"requires_shipping_method": true
},
{
"id": 755357713,
"name": "Mars Fulfillment",
"email": null,
"service_name": "Mars Fulfillment",
"handle": "mars-fulfillment",
"fulfillment_orders_opt_in": true,
"include_pending_stock": false,
"provider_id": null,
"location_id": 24826418,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true,
"admin_graphql_api_id": "gid://shopify/ApiFulfillmentService/755357713",
"permits_sku_sharing": true,
"requires_shipping_method": true
}
]
}

Anchor to GET request, Receive a single FulfillmentService
get
Receive a single FulfillmentService

fulfillmentService

Anchor to Parameters of Receive a single FulfillmentServiceParameters

api_version
string
required
fulfillment_service_id
string
required
Was this section helpful?

Anchor to get-fulfillment-services-fulfillment-service-id-examplesExamples

Get a single fulfillment service by its ID

Path parameters
fulfillment_service_id=755357713
string
required
Was this section helpful?
get

/admin/api/2025-07/fulfillment_services/755357713.json

curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-07/fulfillment_services/755357713.json" \
-H "X-Shopify-Access-Token: {access_token}"

{}

Response

JSON
HTTP/1.1 200 OK
{
"fulfillment_service": {
"id": 755357713,
"name": "Mars Fulfillment",
"email": null,
"service_name": "Mars Fulfillment",
"handle": "mars-fulfillment",
"fulfillment_orders_opt_in": true,
"include_pending_stock": false,
"provider_id": null,
"location_id": 24826418,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true,
"admin_graphql_api_id": "gid://shopify/ApiFulfillmentService/755357713",
"permits_sku_sharing": true,
"requires_shipping_method": true
}
}

Anchor to PUT request, Modify an existing FulfillmentService
put
Modify an existing FulfillmentService

fulfillmentServiceUpdate

Anchor to Parameters of Modify an existing FulfillmentServiceParameters

api_version
string
required
fulfillment_service_id
string
required
callback_url

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

Show callback_url properties
  • Shopify queries the callback_url/fetch_tracking_numbers endpoint to retrieve tracking numbers for orders, if tracking_support is set to true.
  • Shopify queries the callback_url/fetch_stock endpoint to retrieve inventory levels, if inventory_management is set to true.
  • Shopify uses the callback_url/fulfillment_order_notification endpoint to send fulfillment and cancellation requests
fulfillment_orders_opt_in
boolean

Whether the fulfillment service uses the fulfillment order based workflow for managing fulfillments.
As the migration is now finished, the fulfillment_orders_opt_in property is deprecated.

inventory_management
boolean

Whether the fulfillment service tracks product inventory and provides updates to Shopify. Valid values: true and false.

name
string

The name of the fulfillment service as seen by merchants.

permits_sku_sharing
boolean

Whether the fulfillment service can stock inventory alongside other locations.

requires_shipping_method
boolean

Whether the fulfillment service requires products to be physically shipped. Valid values: true and false.

tracking_support
boolean

Whether the fulfillment service provides tracking numbers for packages. Valid values: true and false.

Was this section helpful?

Anchor to put-fulfillment-services-fulfillment-service-id-examplesExamples

Update a fulfillment service

Path parameters
fulfillment_service_id=755357713
string
required
Request body
fulfillment_service
Fulfillment_service resource
Show fulfillment_service properties
fulfillment_service.name:"New Fulfillment Service Name"

The name of the fulfillment service as seen by merchants.

Was this section helpful?
put

/admin/api/2025-07/fulfillment_services/755357713.json

curl -d '{"fulfillment_service":{"id":755357713,"name":"New Fulfillment Service Name"}}' \
-X PUT "https://your-development-store.myshopify.com/admin/api/2025-07/fulfillment_services/755357713.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"

{}

Response

JSON
HTTP/1.1 200 OK
{
"fulfillment_service": {
"id": 755357713,
"name": "New Fulfillment Service Name",
"email": null,
"service_name": "New Fulfillment Service Name",
"handle": "mars-fulfillment",
"fulfillment_orders_opt_in": true,
"include_pending_stock": false,
"provider_id": null,
"location_id": 24826418,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true,
"admin_graphql_api_id": "gid://shopify/ApiFulfillmentService/755357713",
"permits_sku_sharing": true,
"requires_shipping_method": true
}
}

Anchor to DELETE request, Remove an existing FulfillmentService
del
Remove an existing FulfillmentService

fulfillmentServiceDelete

Anchor to Parameters of Remove an existing FulfillmentServiceParameters

api_version
string
required
fulfillment_service_id
string
required
Was this section helpful?

Anchor to delete-fulfillment-services-fulfillment-service-id-examplesExamples

Destroy a fulfillment service

Path parameters
fulfillment_service_id=755357713
string
required
Was this section helpful?
del

/admin/api/2025-07/fulfillment_services/755357713.json

curl -X DELETE "https://your-development-store.myshopify.com/admin/api/2025-07/fulfillment_services/755357713.json" \
-H "X-Shopify-Access-Token: {access_token}"

{}

Response

JSON
HTTP/1.1 200 OK
{}