The REST Admin API is a legacy API as of October 1, 2024. All apps and integrations should be built with the GraphQL Admin API. For details and migration steps, visit our migration guide.

Anchor to section titled 'undefined'

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 inventory levels, 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?
Anchor to section titled 'The FulfillmentService resource'

The FulfillmentService resource

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:
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 section titled 'POST request, Create a new FulfillmentService'

post
Create a new FulfillmentService

fulfillmentServiceCreate
Anchor to section titled 'Parameters of Create a new FulfillmentService'

Parameters

api_version
string
required
callback_url
The callback URL that the fulfillment service has registered for requests. The following considerations apply:
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 section titled 'Examples of Create a new FulfillmentService'

Examples

Request body
fulfillmentservice
Fulfillment_service resource
Was this section helpful?
post
/admin/api/2024-10/fulfillment_services.json
Copy
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/2024-10/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": 1061774487,
    "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": 1072404544,
    "callback_url": "http://google.com/",
    "tracking_support": true,
    "inventory_management": true,
    "admin_graphql_api_id": "gid://shopify/ApiFulfillmentService/1061774487",
    "permits_sku_sharing": true,
    "requires_shipping_method": true
  }
}
Anchor to section titled 'GET request, Receive a list of all FulfillmentServices'

get
Receive a list of all FulfillmentServices

shop
Anchor to section titled 'Parameters of Receive a list of all FulfillmentServices'

Parameters

api_version
string
required
scope
enum
Specify which fulfillment services to retrieve.
Was this section helpful?
Anchor to section titled 'Examples of Receive a list of all FulfillmentServices'

Examples

Query parameters
scope=all
enum
Specify which fulfillment services to retrieve.
Was this section helpful?
get
/admin/api/2024-10/fulfillment_services.json?scope=all
Copy
curl -X GET "https://your-development-store.myshopify.com/admin/api/2024-10/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 section titled 'GET request, Receive a single FulfillmentService'

get
Receive a single FulfillmentService

fulfillmentService
Anchor to section titled 'Parameters of Receive a single FulfillmentService'

Parameters

api_version
string
required
fulfillment_service_id
string
required
Was this section helpful?
Anchor to section titled 'Examples of Receive a single FulfillmentService'

Examples

Path parameters
fulfillmentserviceid=755357713
string
required
Was this section helpful?
get
/admin/api/2024-10/fulfillment_services/755357713.json
Copy
curl -X GET "https://your-development-store.myshopify.com/admin/api/2024-10/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 section titled 'PUT request, Modify an existing FulfillmentService'

put
Modify an existing FulfillmentService

fulfillmentServiceUpdate
Anchor to section titled 'Parameters of Modify an existing FulfillmentService'

Parameters

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:
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 section titled 'Examples of Modify an existing FulfillmentService'

Examples

Path parameters
fulfillmentserviceid=755357713
string
required
Request body
fulfillmentservice
Fulfillment_service resource
Was this section helpful?
put
/admin/api/2024-10/fulfillment_services/755357713.json
Copy
curl -d '{"fulfillment_service":{"id":755357713,"name":"New Fulfillment Service Name"}}' \
-X PUT "https://your-development-store.myshopify.com/admin/api/2024-10/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 section titled 'DELETE request, Remove an existing FulfillmentService'

del
Remove an existing FulfillmentService

fulfillmentServiceDelete
Anchor to section titled 'Parameters of Remove an existing FulfillmentService'

Parameters

api_version
string
required
fulfillment_service_id
string
required
Was this section helpful?
Anchor to section titled 'Examples of Remove an existing FulfillmentService'

Examples

Path parameters
fulfillmentserviceid=755357713
string
required
Was this section helpful?
del
/admin/api/2024-10/fulfillment_services/755357713.json
Copy
curl -X DELETE "https://your-development-store.myshopify.com/admin/api/2024-10/fulfillment_services/755357713.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
HTTP/1.1 200 OK
{}