FulfillmentService
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 that fulfillment service.
Using the Fulfillment Service API, you can register, edit and delete a new fulfillment service.
When you register a new fulfillment service, you will need to expose the two following
GET endpoints rooted in the callback_url
:
fetch_tracking_numbers
: Where Shopify can retrieve tracking numbers for orders.fetch_stock
: Where Shopify can retrieve inventory levels.
Testing the GET endpoints
To make sure you have everything set up correctly, you can test the GET endpoints in your development store by completing the following steps:
- Install your app on a development store.
- Create a fulfillment service using an API request from the app.
- Create at least one product that uses the fulfillment service to manage its inventory (either in the Shopify admin or using the API).
A sample Shopify request for tracking numbers:
Once per hour Shopify will make a request to this endpoint if there are any completed fulfillments awaiting tracking numbers from the remote fulfillment service.
GET/fetch_tracking_numbers
Get tracking numbers for orders
order_names |
The fulfillment names we require tracking numbers for (i.e. #1001.1) |
shop |
The shop's myshopify url |
Get a list of tracking numbers for the following fulfillment names.
http://myapp.com/fetch_tracking_numbers.json?order_names[]=#1001.1&order_names[]=#1002.1&order_names[]=#1003.2
{ "tracking_numbers": { "#1001.1": "qwerty", "#1002.1": "asdfg", "#1003.2": "zxcvb" }, "message": "Successfully received the tracking numbers", "success": true }
A sample Shopify request for inventory levels:
Shopify will make a request for the inventory of an individual SKU when the product is set up initially, its SKU is changed in the Shopify admin, or its inventory management is set to use the fulfillment service. A request for all inventory data will happen once every hour to keep our system up to date with the remote fulfillment service.
GET/fetch_stock
Get inventory levels
max_retries |
The maximum amount of times Shopify will send the request for inventory levels. |
shop |
The shop's myshopify url. |
sku |
The SKU for the Product Variant we need stock levels for. |
timestamp |
The Unix timestamp from when the inventory request was made. |
Get inventory levels for a particular SKU.
https://myapp.com/fetch_stock.json?sku=123&shop=testshop.myshopify.com&max_retries=3×tamp=1532548742
{"123": 1000}
Get inventory levels for all SKUs.
https://myapp.com/fetch_stock.json?shop=testshop.myshopify.com
{"123": 1000, "456": 500}
Fulfillment webhooks
You can subscribe to the fulfillments/create
webhook to receive notifications about new fulfillments. The webhook fires every time an order is marked fulfilled
, and the data is sent to the registered URL.
After receiving and processing the webhook, your service should make a request to complete
the fulfillment. Before filling the order, check the fulfillment
service handle
on the fulfillment record to make sure that the fulfillment is in a pending
state.
You can also integrate the Fulfillment Service API to subscribe to the fulfillments/update
. The webhook fires every time a request comes in to get an update on a fulfillment.
For more information about webhooks, refer to our webhooks tutorial.
You can also update the fulfillment using the API with other information like tracking_numbers
rather than waiting for Shopify to ask for them.
View an open sourced Fulfillment Integration App that demonstrates how to use the Fulfillment API.
Setting fulfillments permissions
Add the write_fulfillments
permission to your requested scopes.
What you can do with FulfillmentService
The Shopify API lets you do the following with the FulfillmentService resource. More detailed versions of these general actions may be available:
- GET /admin/api/2019-10/fulfillment_services.json Receive a list of all FulfillmentServices
- POST /admin/api/2019-10/fulfillment_services.json Create a new FulfillmentService
- GET /admin/api/2019-10/fulfillment_services/{fulfillment_service_id}.json Receive a single FulfillmentService
- PUT /admin/api/2019-10/fulfillment_services/{fulfillment_service_id}.json Modify an existing FulfillmentService
- DELETE /admin/api/2019-10/fulfillment_services/{fulfillment_service_id}.json Remove an existing FulfillmentService
FulfillmentService properties
callback_url |
States the URL endpoint that Shopify needs to retrieve inventory and tracking updates. |
format |
Specifies the format of the API output. Valid values are json and xml. |
handle |
A human-friendly unique string for the fulfillment service generated from its title. |
inventory_management
read-only |
States if the fulfillment service tracks product inventory and provides updates to Shopify. Valid values are "true" and "false". |
location_id |
The unique identifier of the location tied to the fulfillment service |
name |
The name of the fulfillment service as seen by merchants and their customers. |
provider_id |
A unique identifier for the fulfillment service provider. |
requires_shipping_method |
States if the fulfillment service requires products to be physically shipped. Valid values are "true" and "false". |
tracking_support |
States if the fulfillment service provides tracking numbers for packages. Valid values are "true" and "false". |
Endpoints
scope
|
|
List your app's fulfillment services
GET /admin/api/2019-10/fulfillment_services.json
View Response
HTTP/1.1 200 OK
{
"fulfillment_services": [
{
"id": 755357713,
"name": "Mars Fulfillment",
"handle": "mars-fulfillment",
"email": null,
"include_pending_stock": false,
"requires_shipping_method": false,
"service_name": "Mars Fulfillment",
"inventory_management": true,
"tracking_support": true,
"provider_id": null,
"location_id": 48752903
}
]
}
List all of the shop's fulfillment services
GET /admin/api/2019-10/fulfillment_services.json?scope=all
View Response
HTTP/1.1 200 OK
{
"fulfillment_services": [
{
"id": 61629186,
"name": "Venus Fulfillment",
"handle": "venus-fulfillment",
"email": null,
"include_pending_stock": false,
"requires_shipping_method": true,
"service_name": "Venus Fulfillment",
"inventory_management": true,
"tracking_support": true,
"provider_id": null,
"location_id": 61629186
},
{
"id": 755357713,
"name": "Mars Fulfillment",
"handle": "mars-fulfillment",
"email": null,
"include_pending_stock": false,
"requires_shipping_method": false,
"service_name": "Mars Fulfillment",
"inventory_management": true,
"tracking_support": true,
"provider_id": null,
"location_id": 48752903
}
]
}
To create a fulfillment service, you can also use a cURL request that uses that fulfillment_service.json
payload:
curl -X POST -d @fulfillment_service.json -H"Accept:application/json" -H"Content-Type:application/json" -H"X-Shopify-Access-Token:THE_TOKEN_GOES_HERE" https://AUTHORIZED_SHOP.myshopify.com/admin/fulfillment_services
Where THE_TOKEN_GOES_HERE
is replaced by the OAuth token given to you by Shopify and https://AUTHORIZED_SHOP.myshopify.com/admin/fulfillment_services
is replaced by the authorized shop's URL.
Create a fulfillment service
POST /admin/api/2019-10/fulfillment_services.json
{
"fulfillment_service": {
"name": "Jupiter Fulfillment",
"callback_url": "http://google.com",
"inventory_management": true,
"tracking_support": true,
"requires_shipping_method": true,
"format": "json"
}
}
View Response
HTTP/1.1 201 Created
{
"fulfillment_service": {
"id": 1061774487,
"name": "Jupiter Fulfillment",
"handle": "jupiter-fulfillment",
"email": null,
"include_pending_stock": false,
"requires_shipping_method": true,
"service_name": "Jupiter Fulfillment",
"inventory_management": true,
"tracking_support": true,
"provider_id": null,
"location_id": 1059367778
}
}
Get a single fulfillment service by its ID
GET /admin/api/2019-10/fulfillment_services/755357713.json
View Response
HTTP/1.1 200 OK
{
"fulfillment_service": {
"id": 755357713,
"name": "Mars Fulfillment",
"handle": "mars-fulfillment",
"email": null,
"include_pending_stock": false,
"requires_shipping_method": false,
"service_name": "Mars Fulfillment",
"inventory_management": true,
"tracking_support": true,
"provider_id": null,
"location_id": 48752903
}
}
Update a fulfillment service
PUT /admin/api/2019-10/fulfillment_services/755357713.json
{
"fulfillment_service": {
"id": 755357713,
"name": "New Fulfillment Service Name"
}
}
View Response
HTTP/1.1 200 OK
{
"fulfillment_service": {
"id": 755357713,
"name": "New Fulfillment Service Name",
"handle": "new-fulfillment-service-name",
"email": null,
"include_pending_stock": false,
"requires_shipping_method": false,
"service_name": "New Fulfillment Service Name",
"inventory_management": true,
"tracking_support": true,
"provider_id": null,
"location_id": 48752903
}
}
Destroy a fulfillment service
DELETE /admin/api/2019-10/fulfillment_services/755357713.json
View Response
HTTP/1.1 200 OK
{
}
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 that fulfillment service.
Using the Fulfillment Service API, you can register, edit and delete a new fulfillment service.
When you register a new fulfillment service, you will need to expose the two following
GET endpoints rooted in the callback_url
:
fetch_tracking_numbers
: Where Shopify can retrieve tracking numbers for orders.fetch_stock
: Where Shopify can retrieve inventory levels.
Testing the GET endpoints
To make sure you have everything set up correctly, you can test the GET endpoints in your development store by completing the following steps:
- Install your app on a development store.
- Create a fulfillment service using an API request from the app.
- Create at least one product that uses the fulfillment service to manage its inventory (either in the Shopify admin or using the API).
A sample Shopify request for tracking numbers:
Once per hour Shopify will make a request to this endpoint if there are any completed fulfillments awaiting tracking numbers from the remote fulfillment service.
GET/fetch_tracking_numbers
Get tracking numbers for orders
order_names |
The fulfillment names we require tracking numbers for (i.e. #1001.1) |
shop |
The shop's myshopify url |
Get a list of tracking numbers for the following fulfillment names.
http://myapp.com/fetch_tracking_numbers.json?order_names[]=#1001.1&order_names[]=#1002.1&order_names[]=#1003.2
{ "tracking_numbers": { "#1001.1": "qwerty", "#1002.1": "asdfg", "#1003.2": "zxcvb" }, "message": "Successfully received the tracking numbers", "success": true }
A sample Shopify request for inventory levels:
Shopify will make a request for the inventory of an individual SKU when the product is set up initially, its SKU is changed in the Shopify admin, or its inventory management is set to use the fulfillment service. A request for all inventory data will happen once every hour to keep our system up to date with the remote fulfillment service.
GET/fetch_stock
Get inventory levels
max_retries |
The maximum amount of times Shopify will send the request for inventory levels. |
shop |
The shop's myshopify url. |
sku |
The SKU for the Product Variant we need stock levels for. |
timestamp |
The Unix timestamp from when the inventory request was made. |
Get inventory levels for a particular SKU.
https://myapp.com/fetch_stock.json?sku=123&shop=testshop.myshopify.com&max_retries=3×tamp=1532548742
{"123": 1000}
Get inventory levels for all SKUs.
https://myapp.com/fetch_stock.json?shop=testshop.myshopify.com
{"123": 1000, "456": 500}
Fulfillment webhooks
You can subscribe to the fulfillments/create
webhook to receive notifications about new fulfillments. The webhook fires every time an order is marked fulfilled
, and the data is sent to the registered URL.
After receiving and processing the webhook, your service should make a request to complete
the fulfillment. Before filling the order, check the fulfillment
service handle
on the fulfillment record to make sure that the fulfillment is in a pending
state.
You can also integrate the Fulfillment Service API to subscribe to the fulfillments/update
. The webhook fires every time a request comes in to get an update on a fulfillment.
For more information about webhooks, refer to our webhooks tutorial.
You can also update the fulfillment using the API with other information like tracking_numbers
rather than waiting for Shopify to ask for them.
View an open sourced Fulfillment Integration App that demonstrates how to use the Fulfillment API.
Setting fulfillments permissions
Add the write_fulfillments
permission to your requested scopes.
What you can do with FulfillmentService
The Shopify API lets you do the following with the FulfillmentService resource. More detailed versions of these general actions may be available:
- GET /admin/api/2020-01/fulfillment_services.json Receive a list of all FulfillmentServices
- POST /admin/api/2020-01/fulfillment_services.json Create a new FulfillmentService
- GET /admin/api/2020-01/fulfillment_services/{fulfillment_service_id}.json Receive a single FulfillmentService
- PUT /admin/api/2020-01/fulfillment_services/{fulfillment_service_id}.json Modify an existing FulfillmentService
- DELETE /admin/api/2020-01/fulfillment_services/{fulfillment_service_id}.json Remove an existing FulfillmentService
FulfillmentService properties
callback_url |
States the URL endpoint that Shopify needs to retrieve inventory and tracking updates. |
format |
Specifies the format of the API output. Valid values are json and xml. |
fulfillment_orders_opt_in |
Whether the fulfillment service wants to register for APIs related to fulfillment orders. To manage fulfillments using fulfillment orders, see Manage fulfillments with Fulfillment and FulfillmentOrder resources. |
handle |
A human-friendly unique string for the fulfillment service generated from its title. |
inventory_management
read-only |
States if the fulfillment service tracks product inventory and provides updates to Shopify. Valid values are "true" and "false". |
location_id |
The unique identifier of the location tied to the fulfillment service |
name |
The name of the fulfillment service as seen by merchants and their customers. |
provider_id |
A unique identifier for the fulfillment service provider. |
requires_shipping_method |
States if the fulfillment service requires products to be physically shipped. Valid values are "true" and "false". |
tracking_support |
States if the fulfillment service provides tracking numbers for packages. Valid values are "true" and "false". |
Endpoints
scope
|
|
List your app's fulfillment services
GET /admin/api/2020-01/fulfillment_services.json
View Response
HTTP/1.1 200 OK
{
"fulfillment_services": [
{
"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": 48752903,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
]
}
List all of the shop's fulfillment services
GET /admin/api/2020-01/fulfillment_services.json?scope=all
View Response
HTTP/1.1 200 OK
{
"fulfillment_services": [
{
"id": 61629186,
"name": "Venus Fulfillment",
"email": null,
"service_name": "Venus Fulfillment",
"handle": "venus-fulfillment",
"fulfillment_orders_opt_in": false,
"include_pending_stock": false,
"provider_id": null,
"location_id": 61629186,
"callback_url": null,
"tracking_support": true,
"inventory_management": 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": 48752903,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
]
}
To create a fulfillment service, you can also use a cURL request that uses that fulfillment_service.json
payload:
curl -X POST -d @fulfillment_service.json -H"Accept:application/json" -H"Content-Type:application/json" -H"X-Shopify-Access-Token:THE_TOKEN_GOES_HERE" https://AUTHORIZED_SHOP.myshopify.com/admin/fulfillment_services
Where THE_TOKEN_GOES_HERE
is replaced by the OAuth token given to you by Shopify and https://AUTHORIZED_SHOP.myshopify.com/admin/fulfillment_services
is replaced by the authorized shop's URL.
Create a fulfillment service
POST /admin/api/2020-01/fulfillment_services.json
{
"fulfillment_service": {
"name": "Jupiter Fulfillment",
"callback_url": "http://google.com",
"inventory_management": true,
"tracking_support": true,
"requires_shipping_method": true,
"format": "json"
}
}
View Response
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": false,
"include_pending_stock": false,
"provider_id": null,
"location_id": 1059367779,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
}
Get a single fulfillment service by its ID
GET /admin/api/2020-01/fulfillment_services/755357713.json
View Response
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": 48752903,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
}
Update a fulfillment service
PUT /admin/api/2020-01/fulfillment_services/755357713.json
{
"fulfillment_service": {
"id": 755357713,
"name": "New Fulfillment Service Name"
}
}
View Response
HTTP/1.1 200 OK
{
"fulfillment_service": {
"id": 755357713,
"name": "New Fulfillment Service Name",
"email": null,
"service_name": "New Fulfillment Service Name",
"handle": "new-fulfillment-service-name",
"fulfillment_orders_opt_in": true,
"include_pending_stock": false,
"provider_id": null,
"location_id": 48752903,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
}
Destroy a fulfillment service
DELETE /admin/api/2020-01/fulfillment_services/755357713.json
View Response
HTTP/1.1 200 OK
{
}
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 that fulfillment service.
Using the Fulfillment Service API, you can register, edit and delete a new fulfillment service.
When you register a new fulfillment service, you will need to expose the two following
GET endpoints rooted in the callback_url
:
fetch_tracking_numbers
: Where Shopify can retrieve tracking numbers for orders.fetch_stock
: Where Shopify can retrieve inventory levels.
Testing the GET endpoints
To make sure you have everything set up correctly, you can test the GET endpoints in your development store by completing the following steps:
- Install your app on a development store.
- Create a fulfillment service using an API request from the app.
- Create at least one product that uses the fulfillment service to manage its inventory (either in the Shopify admin or using the API).
A sample Shopify request for tracking numbers:
Once per hour Shopify will make a request to this endpoint if there are any completed fulfillments awaiting tracking numbers from the remote fulfillment service.
GET/fetch_tracking_numbers
Get tracking numbers for orders
order_names |
The fulfillment names we require tracking numbers for (i.e. #1001.1) |
shop |
The shop's myshopify url |
Get a list of tracking numbers for the following fulfillment names.
http://myapp.com/fetch_tracking_numbers.json?order_names[]=#1001.1&order_names[]=#1002.1&order_names[]=#1003.2
{ "tracking_numbers": { "#1001.1": "qwerty", "#1002.1": "asdfg", "#1003.2": "zxcvb" }, "message": "Successfully received the tracking numbers", "success": true }
A sample Shopify request for inventory levels:
Shopify will make a request for the inventory of an individual SKU when the product is set up initially, its SKU is changed in the Shopify admin, or its inventory management is set to use the fulfillment service. A request for all inventory data will happen once every hour to keep our system up to date with the remote fulfillment service.
GET/fetch_stock
Get inventory levels
max_retries |
The maximum amount of times Shopify will send the request for inventory levels. |
shop |
The shop's myshopify url. |
sku |
The SKU for the Product Variant we need stock levels for. |
timestamp |
The Unix timestamp from when the inventory request was made. |
Get inventory levels for a particular SKU.
https://myapp.com/fetch_stock.json?sku=123&shop=testshop.myshopify.com&max_retries=3×tamp=1532548742
{"123": 1000}
Get inventory levels for all SKUs.
https://myapp.com/fetch_stock.json?shop=testshop.myshopify.com
{"123": 1000, "456": 500}
Fulfillment webhooks
You can subscribe to the fulfillments/create
webhook to receive notifications about new fulfillments. The webhook fires every time an order is marked fulfilled
, and the data is sent to the registered URL.
After receiving and processing the webhook, your service should make a request to complete
the fulfillment. Before filling the order, check the fulfillment
service handle
on the fulfillment record to make sure that the fulfillment is in a pending
state.
You can also integrate the Fulfillment Service API to subscribe to the fulfillments/update
. The webhook fires every time a request comes in to get an update on a fulfillment.
For more information about webhooks, refer to our webhooks tutorial.
You can also update the fulfillment using the API with other information like tracking_numbers
rather than waiting for Shopify to ask for them.
View an open sourced Fulfillment Integration App that demonstrates how to use the Fulfillment API.
Setting fulfillments permissions
Add the write_fulfillments
permission to your requested scopes.
What you can do with FulfillmentService
The Shopify API lets you do the following with the FulfillmentService resource. More detailed versions of these general actions may be available:
- GET /admin/api/2020-04/fulfillment_services.json Receive a list of all FulfillmentServices
- POST /admin/api/2020-04/fulfillment_services.json Create a new FulfillmentService
- GET /admin/api/2020-04/fulfillment_services/{fulfillment_service_id}.json Receive a single FulfillmentService
- PUT /admin/api/2020-04/fulfillment_services/{fulfillment_service_id}.json Modify an existing FulfillmentService
- DELETE /admin/api/2020-04/fulfillment_services/{fulfillment_service_id}.json Remove an existing FulfillmentService
FulfillmentService properties
callback_url |
States the URL endpoint that Shopify needs to retrieve inventory and tracking updates. |
format |
Specifies the format of the API output. Valid values are json and xml. |
fulfillment_orders_opt_in |
Whether the fulfillment service wants to register for APIs related to fulfillment orders. To manage fulfillments using fulfillment orders, see Manage fulfillments with Fulfillment and FulfillmentOrder resources. |
handle |
A human-friendly unique string for the fulfillment service generated from its title. |
inventory_management |
States if the fulfillment service tracks product inventory and provides updates to Shopify. Valid values are "true" and "false". |
location_id |
The unique identifier of the location tied to the fulfillment service |
name |
The name of the fulfillment service as seen by merchants and their customers. |
provider_id |
A unique identifier for the fulfillment service provider. |
requires_shipping_method |
States if the fulfillment service requires products to be physically shipped. Valid values are "true" and "false". |
tracking_support |
States if the fulfillment service provides tracking numbers for packages. Valid values are "true" and "false". |
Endpoints
scope
|
|
List your app's fulfillment services
GET /admin/api/2020-04/fulfillment_services.json
View Response
HTTP/1.1 200 OK
{
"fulfillment_services": [
{
"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": 48752903,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
]
}
List all of the shop's fulfillment services
GET /admin/api/2020-04/fulfillment_services.json?scope=all
View Response
HTTP/1.1 200 OK
{
"fulfillment_services": [
{
"id": 61629186,
"name": "Venus Fulfillment",
"email": null,
"service_name": "Venus Fulfillment",
"handle": "venus-fulfillment",
"fulfillment_orders_opt_in": false,
"include_pending_stock": false,
"provider_id": null,
"location_id": 61629186,
"callback_url": null,
"tracking_support": true,
"inventory_management": 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": 48752903,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
]
}
To create a fulfillment service, you can also use a cURL request that uses that fulfillment_service.json
payload:
curl -X POST -d @fulfillment_service.json -H"Accept:application/json" -H"Content-Type:application/json" -H"X-Shopify-Access-Token:THE_TOKEN_GOES_HERE" https://AUTHORIZED_SHOP.myshopify.com/admin/fulfillment_services
Where THE_TOKEN_GOES_HERE
is replaced by the OAuth token given to you by Shopify and https://AUTHORIZED_SHOP.myshopify.com/admin/fulfillment_services
is replaced by the authorized shop's URL.
Create a fulfillment service
POST /admin/api/2020-04/fulfillment_services.json
{
"fulfillment_service": {
"name": "Jupiter Fulfillment",
"callback_url": "http://google.com",
"inventory_management": true,
"tracking_support": true,
"requires_shipping_method": true,
"format": "json"
}
}
View Response
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": false,
"include_pending_stock": false,
"provider_id": null,
"location_id": 1059367779,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
}
Get a single fulfillment service by its ID
GET /admin/api/2020-04/fulfillment_services/755357713.json
View Response
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": 48752903,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
}
Update a fulfillment service
PUT /admin/api/2020-04/fulfillment_services/755357713.json
{
"fulfillment_service": {
"id": 755357713,
"name": "New Fulfillment Service Name"
}
}
View Response
HTTP/1.1 200 OK
{
"fulfillment_service": {
"id": 755357713,
"name": "New Fulfillment Service Name",
"email": null,
"service_name": "New Fulfillment Service Name",
"handle": "new-fulfillment-service-name",
"fulfillment_orders_opt_in": true,
"include_pending_stock": false,
"provider_id": null,
"location_id": 48752903,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
}
Destroy a fulfillment service
DELETE /admin/api/2020-04/fulfillment_services/755357713.json
View Response
HTTP/1.1 200 OK
{
}
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 that fulfillment service.
Using the Fulfillment Service API, you can register, edit and delete a new fulfillment service.
When you register a new fulfillment service, you will need to expose the two following
GET endpoints rooted in the callback_url
:
fetch_tracking_numbers
: Where Shopify can retrieve tracking numbers for orders.fetch_stock
: Where Shopify can retrieve inventory levels.
Testing the GET endpoints
To make sure you have everything set up correctly, you can test the GET endpoints in your development store by completing the following steps:
- Install your app on a development store.
- Create a fulfillment service using an API request from the app.
- Create at least one product that uses the fulfillment service to manage its inventory (either in the Shopify admin or using the API).
A sample Shopify request for tracking numbers:
Once per hour Shopify will make a request to this endpoint if there are any completed fulfillments awaiting tracking numbers from the remote fulfillment service.
GET/fetch_tracking_numbers
Get tracking numbers for orders
order_names |
The fulfillment names we require tracking numbers for (i.e. #1001.1) |
shop |
The shop's myshopify url |
Get a list of tracking numbers for the following fulfillment names.
http://myapp.com/fetch_tracking_numbers.json?order_names[]=#1001.1&order_names[]=#1002.1&order_names[]=#1003.2
{ "tracking_numbers": { "#1001.1": "qwerty", "#1002.1": "asdfg", "#1003.2": "zxcvb" }, "message": "Successfully received the tracking numbers", "success": true }
A sample Shopify request for inventory levels:
Shopify will make a request for the inventory of an individual SKU when the product is set up initially, its SKU is changed in the Shopify admin, or its inventory management is set to use the fulfillment service. A request for all inventory data will happen once every hour to keep our system up to date with the remote fulfillment service.
GET/fetch_stock
Get inventory levels
max_retries |
The maximum amount of times Shopify will send the request for inventory levels. |
shop |
The shop's myshopify url. |
sku |
The SKU for the Product Variant we need stock levels for. |
timestamp |
The Unix timestamp from when the inventory request was made. |
Get inventory levels for a particular SKU.
https://myapp.com/fetch_stock.json?sku=123&shop=testshop.myshopify.com&max_retries=3×tamp=1532548742
{"123": 1000}
Get inventory levels for all SKUs.
https://myapp.com/fetch_stock.json?shop=testshop.myshopify.com
{"123": 1000, "456": 500}
Fulfillment webhooks
You can subscribe to the fulfillments/create
webhook to receive notifications about new fulfillments. The webhook fires every time an order is marked fulfilled
, and the data is sent to the registered URL.
After receiving and processing the webhook, your service should make a request to complete
the fulfillment. Before filling the order, check the fulfillment
service handle
on the fulfillment record to make sure that the fulfillment is in a pending
state.
You can also integrate the Fulfillment Service API to subscribe to the fulfillments/update
. The webhook fires every time a request comes in to get an update on a fulfillment.
For more information about webhooks, refer to our webhooks tutorial.
You can also update the fulfillment using the API with other information like tracking_numbers
rather than waiting for Shopify to ask for them.
View an open sourced Fulfillment Integration App that demonstrates how to use the Fulfillment API.
Setting fulfillments permissions
Add the write_fulfillments
permission to your requested scopes.
What you can do with FulfillmentService
The Shopify API lets you do the following with the FulfillmentService resource. More detailed versions of these general actions may be available:
- GET /admin/api/2020-07/fulfillment_services.json Receive a list of all FulfillmentServices
- POST /admin/api/2020-07/fulfillment_services.json Create a new FulfillmentService
- GET /admin/api/2020-07/fulfillment_services/{fulfillment_service_id}.json Receive a single FulfillmentService
- PUT /admin/api/2020-07/fulfillment_services/{fulfillment_service_id}.json Modify an existing FulfillmentService
- DELETE /admin/api/2020-07/fulfillment_services/{fulfillment_service_id}.json Remove an existing FulfillmentService
FulfillmentService properties
callback_url |
States the URL endpoint that Shopify needs to retrieve inventory and tracking updates. |
format |
Specifies the format of the API output. Valid values are json and xml. |
fulfillment_orders_opt_in |
Whether the fulfillment service wants to register for APIs related to fulfillment orders. To manage fulfillments using fulfillment orders, see Manage fulfillments with Fulfillment and FulfillmentOrder resources. |
handle |
A human-friendly unique string for the fulfillment service generated from its title. |
inventory_management |
States if the fulfillment service tracks product inventory and provides updates to Shopify. Valid values are "true" and "false". |
location_id |
The unique identifier of the location tied to the fulfillment service |
name |
The name of the fulfillment service as seen by merchants and their customers. |
provider_id |
A unique identifier for the fulfillment service provider. |
requires_shipping_method |
States if the fulfillment service requires products to be physically shipped. Valid values are "true" and "false". |
tracking_support |
States if the fulfillment service provides tracking numbers for packages. Valid values are "true" and "false". |
Endpoints
scope
|
|
List your app's fulfillment services
GET /admin/api/2020-07/fulfillment_services.json
View Response
HTTP/1.1 200 OK
{
"fulfillment_services": [
{
"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": 48752903,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
]
}
List all of the shop's fulfillment services
GET /admin/api/2020-07/fulfillment_services.json?scope=all
View Response
HTTP/1.1 200 OK
{
"fulfillment_services": [
{
"id": 61629186,
"name": "Venus Fulfillment",
"email": null,
"service_name": "Venus Fulfillment",
"handle": "venus-fulfillment",
"fulfillment_orders_opt_in": false,
"include_pending_stock": false,
"provider_id": null,
"location_id": 61629186,
"callback_url": null,
"tracking_support": true,
"inventory_management": 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": 48752903,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
]
}
To create a fulfillment service, you can also use a cURL request that uses that fulfillment_service.json
payload:
curl -X POST -d @fulfillment_service.json -H"Accept:application/json" -H"Content-Type:application/json" -H"X-Shopify-Access-Token:THE_TOKEN_GOES_HERE" https://AUTHORIZED_SHOP.myshopify.com/admin/fulfillment_services
Where THE_TOKEN_GOES_HERE
is replaced by the OAuth token given to you by Shopify and https://AUTHORIZED_SHOP.myshopify.com/admin/fulfillment_services
is replaced by the authorized shop's URL.
Create a fulfillment service
POST /admin/api/2020-07/fulfillment_services.json
{
"fulfillment_service": {
"name": "Jupiter Fulfillment",
"callback_url": "http://google.com",
"inventory_management": true,
"tracking_support": true,
"requires_shipping_method": true,
"format": "json"
}
}
View Response
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": false,
"include_pending_stock": false,
"provider_id": null,
"location_id": 1059367779,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
}
Get a single fulfillment service by its ID
GET /admin/api/2020-07/fulfillment_services/755357713.json
View Response
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": 48752903,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
}
Update a fulfillment service
PUT /admin/api/2020-07/fulfillment_services/755357713.json
{
"fulfillment_service": {
"id": 755357713,
"name": "New Fulfillment Service Name"
}
}
View Response
HTTP/1.1 200 OK
{
"fulfillment_service": {
"id": 755357713,
"name": "New Fulfillment Service Name",
"email": null,
"service_name": "New Fulfillment Service Name",
"handle": "new-fulfillment-service-name",
"fulfillment_orders_opt_in": true,
"include_pending_stock": false,
"provider_id": null,
"location_id": 48752903,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
}
Destroy a fulfillment service
DELETE /admin/api/2020-07/fulfillment_services/755357713.json
View Response
HTTP/1.1 200 OK
{
}
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 that fulfillment service.
Using the Fulfillment Service API, you can register, edit and delete a new fulfillment service.
When you register a new fulfillment service, you will need to expose the two following
GET endpoints rooted in the callback_url
:
fetch_tracking_numbers
: Where Shopify can retrieve tracking numbers for orders.fetch_stock
: Where Shopify can retrieve inventory levels.
Testing the GET endpoints
To make sure you have everything set up correctly, you can test the GET endpoints in your development store by completing the following steps:
- Install your app on a development store.
- Create a fulfillment service using an API request from the app.
- Create at least one product that uses the fulfillment service to manage its inventory (either in the Shopify admin or using the API).
A sample Shopify request for tracking numbers:
Once per hour Shopify will make a request to this endpoint if there are any completed fulfillments awaiting tracking numbers from the remote fulfillment service.
GET/fetch_tracking_numbers
Get tracking numbers for orders
order_names |
The fulfillment names we require tracking numbers for (i.e. #1001.1) |
shop |
The shop's myshopify url |
Get a list of tracking numbers for the following fulfillment names.
http://myapp.com/fetch_tracking_numbers.json?order_names[]=#1001.1&order_names[]=#1002.1&order_names[]=#1003.2
{ "tracking_numbers": { "#1001.1": "qwerty", "#1002.1": "asdfg", "#1003.2": "zxcvb" }, "message": "Successfully received the tracking numbers", "success": true }
A sample Shopify request for inventory levels:
Shopify will make a request for the inventory of an individual SKU when the product is set up initially, its SKU is changed in the Shopify admin, or its inventory management is set to use the fulfillment service. A request for all inventory data will happen once every hour to keep our system up to date with the remote fulfillment service.
GET/fetch_stock
Get inventory levels
max_retries |
The maximum amount of times Shopify will send the request for inventory levels. |
shop |
The shop's myshopify url. |
sku |
The SKU for the Product Variant we need stock levels for. |
timestamp |
The Unix timestamp from when the inventory request was made. |
Get inventory levels for a particular SKU.
https://myapp.com/fetch_stock.json?sku=123&shop=testshop.myshopify.com&max_retries=3×tamp=1532548742
{"123": 1000}
Get inventory levels for all SKUs.
https://myapp.com/fetch_stock.json?shop=testshop.myshopify.com
{"123": 1000, "456": 500}
Fulfillment webhooks
You can subscribe to the fulfillments/create
webhook to receive notifications about new fulfillments. The webhook fires every time an order is marked fulfilled
, and the data is sent to the registered URL.
After receiving and processing the webhook, your service should make a request to complete
the fulfillment. Before filling the order, check the fulfillment
service handle
on the fulfillment record to make sure that the fulfillment is in a pending
state.
You can also integrate the Fulfillment Service API to subscribe to the fulfillments/update
. The webhook fires every time a request comes in to get an update on a fulfillment.
For more information about webhooks, refer to our webhooks tutorial.
You can also update the fulfillment using the API with other information like tracking_numbers
rather than waiting for Shopify to ask for them.
View an open sourced Fulfillment Integration App that demonstrates how to use the Fulfillment API.
Setting fulfillments permissions
Add the write_fulfillments
permission to your requested scopes.
What you can do with FulfillmentService
The Shopify API lets you do the following with the FulfillmentService resource. More detailed versions of these general actions may be available:
- GET /admin/api/2020-10/fulfillment_services.json Receive a list of all FulfillmentServices
- POST /admin/api/2020-10/fulfillment_services.json Create a new FulfillmentService
- GET /admin/api/2020-10/fulfillment_services/{fulfillment_service_id}.json Receive a single FulfillmentService
- PUT /admin/api/2020-10/fulfillment_services/{fulfillment_service_id}.json Modify an existing FulfillmentService
- DELETE /admin/api/2020-10/fulfillment_services/{fulfillment_service_id}.json Remove an existing FulfillmentService
FulfillmentService properties
callback_url |
States the URL endpoint that Shopify needs to retrieve inventory and tracking updates. |
format |
Specifies the format of the API output. Valid values are json and xml. |
fulfillment_orders_opt_in |
Whether the fulfillment service wants to register for APIs related to fulfillment orders. To manage fulfillments using fulfillment orders, see Manage fulfillments with Fulfillment and FulfillmentOrder resources. |
handle |
A human-friendly unique string for the fulfillment service generated from its title. |
inventory_management |
States if the fulfillment service tracks product inventory and provides updates to Shopify. Valid values are "true" and "false". |
location_id |
The unique identifier of the location tied to the fulfillment service |
name |
The name of the fulfillment service as seen by merchants and their customers. |
provider_id |
A unique identifier for the fulfillment service provider. |
requires_shipping_method |
States if the fulfillment service requires products to be physically shipped. Valid values are "true" and "false". |
tracking_support |
States if the fulfillment service provides tracking numbers for packages. Valid values are "true" and "false". |
Endpoints
scope
|
|
List your app's fulfillment services
GET /admin/api/2020-10/fulfillment_services.json
View Response
HTTP/1.1 200 OK
{
"fulfillment_services": [
{
"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": 48752903,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
]
}
List all of the shop's fulfillment services
GET /admin/api/2020-10/fulfillment_services.json?scope=all
View Response
HTTP/1.1 200 OK
{
"fulfillment_services": [
{
"id": 61629186,
"name": "Venus Fulfillment",
"email": null,
"service_name": "Venus Fulfillment",
"handle": "venus-fulfillment",
"fulfillment_orders_opt_in": false,
"include_pending_stock": false,
"provider_id": null,
"location_id": 61629186,
"callback_url": null,
"tracking_support": true,
"inventory_management": 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": 48752903,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
]
}
To create a fulfillment service, you can also use a cURL request that uses that fulfillment_service.json
payload:
curl -X POST -d @fulfillment_service.json -H"Accept:application/json" -H"Content-Type:application/json" -H"X-Shopify-Access-Token:THE_TOKEN_GOES_HERE" https://AUTHORIZED_SHOP.myshopify.com/admin/fulfillment_services
Where THE_TOKEN_GOES_HERE
is replaced by the OAuth token given to you by Shopify and https://AUTHORIZED_SHOP.myshopify.com/admin/fulfillment_services
is replaced by the authorized shop's URL.
Create a fulfillment service
POST /admin/api/2020-10/fulfillment_services.json
{
"fulfillment_service": {
"name": "Jupiter Fulfillment",
"callback_url": "http://google.com",
"inventory_management": true,
"tracking_support": true,
"requires_shipping_method": true,
"format": "json"
}
}
View Response
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": false,
"include_pending_stock": false,
"provider_id": null,
"location_id": 1059367779,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
}
Get a single fulfillment service by its ID
GET /admin/api/2020-10/fulfillment_services/755357713.json
View Response
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": 48752903,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
}
Update a fulfillment service
PUT /admin/api/2020-10/fulfillment_services/755357713.json
{
"fulfillment_service": {
"id": 755357713,
"name": "New Fulfillment Service Name"
}
}
View Response
HTTP/1.1 200 OK
{
"fulfillment_service": {
"id": 755357713,
"name": "New Fulfillment Service Name",
"email": null,
"service_name": "New Fulfillment Service Name",
"handle": "new-fulfillment-service-name",
"fulfillment_orders_opt_in": true,
"include_pending_stock": false,
"provider_id": null,
"location_id": 48752903,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
}
Destroy a fulfillment service
DELETE /admin/api/2020-10/fulfillment_services/755357713.json
View Response
HTTP/1.1 200 OK
{
}
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 that fulfillment service.
Using the Fulfillment Service API, you can register, edit and delete a new fulfillment service.
When you register a new fulfillment service, you will need to expose the two following
GET endpoints rooted in the callback_url
:
fetch_tracking_numbers
: Where Shopify can retrieve tracking numbers for orders.fetch_stock
: Where Shopify can retrieve inventory levels.
Testing the GET endpoints
To make sure you have everything set up correctly, you can test the GET endpoints in your development store by completing the following steps:
- Install your app on a development store.
- Create a fulfillment service using an API request from the app.
- Create at least one product that uses the fulfillment service to manage its inventory (either in the Shopify admin or using the API).
A sample Shopify request for tracking numbers:
Once per hour Shopify will make a request to this endpoint if there are any completed fulfillments awaiting tracking numbers from the remote fulfillment service.
GET/fetch_tracking_numbers
Get tracking numbers for orders
order_names |
The fulfillment names we require tracking numbers for (i.e. #1001.1) |
shop |
The shop's myshopify url |
Get a list of tracking numbers for the following fulfillment names.
http://myapp.com/fetch_tracking_numbers.json?order_names[]=#1001.1&order_names[]=#1002.1&order_names[]=#1003.2
{ "tracking_numbers": { "#1001.1": "qwerty", "#1002.1": "asdfg", "#1003.2": "zxcvb" }, "message": "Successfully received the tracking numbers", "success": true }
A sample Shopify request for inventory levels:
Shopify will make a request for the inventory of an individual SKU when the product is set up initially, its SKU is changed in the Shopify admin, or its inventory management is set to use the fulfillment service. A request for all inventory data will happen once every hour to keep our system up to date with the remote fulfillment service.
GET/fetch_stock
Get inventory levels
max_retries |
The maximum amount of times Shopify will send the request for inventory levels. |
shop |
The shop's myshopify url. |
sku |
The SKU for the Product Variant we need stock levels for. |
timestamp |
The Unix timestamp from when the inventory request was made. |
Get inventory levels for a particular SKU.
https://myapp.com/fetch_stock.json?sku=123&shop=testshop.myshopify.com&max_retries=3×tamp=1532548742
{"123": 1000}
Get inventory levels for all SKUs.
https://myapp.com/fetch_stock.json?shop=testshop.myshopify.com
{"123": 1000, "456": 500}
Fulfillment webhooks
You can subscribe to the fulfillments/create
webhook to receive notifications about new fulfillments. The webhook fires every time an order is marked fulfilled
, and the data is sent to the registered URL.
After receiving and processing the webhook, your service should make a request to complete
the fulfillment. Before filling the order, check the fulfillment
service handle
on the fulfillment record to make sure that the fulfillment is in a pending
state.
You can also integrate the Fulfillment Service API to subscribe to the fulfillments/update
. The webhook fires every time a request comes in to get an update on a fulfillment.
For more information about webhooks, refer to our webhooks tutorial.
You can also update the fulfillment using the API with other information like tracking_numbers
rather than waiting for Shopify to ask for them.
View an open sourced Fulfillment Integration App that demonstrates how to use the Fulfillment API.
Setting fulfillments permissions
Add the write_fulfillments
permission to your requested scopes.
What you can do with FulfillmentService
The Shopify API lets you do the following with the FulfillmentService resource. More detailed versions of these general actions may be available:
- GET /admin/api/2021-01/fulfillment_services.json Receive a list of all FulfillmentServices
- POST /admin/api/2021-01/fulfillment_services.json Create a new FulfillmentService
- GET /admin/api/2021-01/fulfillment_services/{fulfillment_service_id}.json Receive a single FulfillmentService
- PUT /admin/api/2021-01/fulfillment_services/{fulfillment_service_id}.json Modify an existing FulfillmentService
- DELETE /admin/api/2021-01/fulfillment_services/{fulfillment_service_id}.json Remove an existing FulfillmentService
FulfillmentService properties
callback_url |
States the URL endpoint that Shopify needs to retrieve inventory and tracking updates. |
format |
Specifies the format of the API output. Valid values are json and xml. |
fulfillment_orders_opt_in |
Whether the fulfillment service wants to register for APIs related to fulfillment orders. To manage fulfillments using fulfillment orders, see Manage fulfillments with Fulfillment and FulfillmentOrder resources. |
handle |
A human-friendly unique string for the fulfillment service generated from its title. |
inventory_management |
States if the fulfillment service tracks product inventory and provides updates to Shopify. Valid values are "true" and "false". |
location_id |
The unique identifier of the location tied to the fulfillment service |
name |
The name of the fulfillment service as seen by merchants and their customers. |
provider_id |
A unique identifier for the fulfillment service provider. |
requires_shipping_method |
States if the fulfillment service requires products to be physically shipped. Valid values are "true" and "false". |
tracking_support |
States if the fulfillment service provides tracking numbers for packages. Valid values are "true" and "false". |
Endpoints
scope
|
|
List your app's fulfillment services
GET /admin/api/2021-01/fulfillment_services.json
View Response
HTTP/1.1 200 OK
{
"fulfillment_services": [
{
"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": 48752903,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
]
}
List all of the shop's fulfillment services
GET /admin/api/2021-01/fulfillment_services.json?scope=all
View Response
HTTP/1.1 200 OK
{
"fulfillment_services": [
{
"id": 61629186,
"name": "Venus Fulfillment",
"email": null,
"service_name": "Venus Fulfillment",
"handle": "venus-fulfillment",
"fulfillment_orders_opt_in": false,
"include_pending_stock": false,
"provider_id": null,
"location_id": 61629186,
"callback_url": null,
"tracking_support": true,
"inventory_management": 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": 48752903,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
]
}
To create a fulfillment service, you can also use a cURL request that uses that fulfillment_service.json
payload:
curl -X POST -d @fulfillment_service.json -H"Accept:application/json" -H"Content-Type:application/json" -H"X-Shopify-Access-Token:THE_TOKEN_GOES_HERE" https://AUTHORIZED_SHOP.myshopify.com/admin/fulfillment_services
Where THE_TOKEN_GOES_HERE
is replaced by the OAuth token given to you by Shopify and https://AUTHORIZED_SHOP.myshopify.com/admin/fulfillment_services
is replaced by the authorized shop's URL.
Create a fulfillment service
POST /admin/api/2021-01/fulfillment_services.json
{
"fulfillment_service": {
"name": "Jupiter Fulfillment",
"callback_url": "http://google.com",
"inventory_management": true,
"tracking_support": true,
"requires_shipping_method": true,
"format": "json"
}
}
View Response
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": false,
"include_pending_stock": false,
"provider_id": null,
"location_id": 1059367779,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
}
Get a single fulfillment service by its ID
GET /admin/api/2021-01/fulfillment_services/755357713.json
View Response
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": 48752903,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
}
Update a fulfillment service
PUT /admin/api/2021-01/fulfillment_services/755357713.json
{
"fulfillment_service": {
"id": 755357713,
"name": "New Fulfillment Service Name"
}
}
View Response
HTTP/1.1 200 OK
{
"fulfillment_service": {
"id": 755357713,
"name": "New Fulfillment Service Name",
"email": null,
"service_name": "New Fulfillment Service Name",
"handle": "new-fulfillment-service-name",
"fulfillment_orders_opt_in": true,
"include_pending_stock": false,
"provider_id": null,
"location_id": 48752903,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
}
Destroy a fulfillment service
DELETE /admin/api/2021-01/fulfillment_services/755357713.json
View Response
HTTP/1.1 200 OK
{
}
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 that fulfillment service.
Using the Fulfillment Service API, you can register, edit and delete a new fulfillment service.
When you register a new fulfillment service, you will need to expose the two following
GET endpoints rooted in the callback_url
:
fetch_tracking_numbers
: Where Shopify can retrieve tracking numbers for orders.fetch_stock
: Where Shopify can retrieve inventory levels.
Testing the GET endpoints
To make sure you have everything set up correctly, you can test the GET endpoints in your development store by completing the following steps:
- Install your app on a development store.
- Create a fulfillment service using an API request from the app.
- Create at least one product that uses the fulfillment service to manage its inventory (either in the Shopify admin or using the API).
A sample Shopify request for tracking numbers:
Once per hour Shopify will make a request to this endpoint if there are any completed fulfillments awaiting tracking numbers from the remote fulfillment service.
GET/fetch_tracking_numbers
Get tracking numbers for orders
order_names |
The fulfillment names we require tracking numbers for (i.e. #1001.1) |
shop |
The shop's myshopify url |
Get a list of tracking numbers for the following fulfillment names.
http://myapp.com/fetch_tracking_numbers.json?order_names[]=#1001.1&order_names[]=#1002.1&order_names[]=#1003.2
{ "tracking_numbers": { "#1001.1": "qwerty", "#1002.1": "asdfg", "#1003.2": "zxcvb" }, "message": "Successfully received the tracking numbers", "success": true }
A sample Shopify request for inventory levels:
Shopify will make a request for the inventory of an individual SKU when the product is set up initially, its SKU is changed in the Shopify admin, or its inventory management is set to use the fulfillment service. A request for all inventory data will happen once every hour to keep our system up to date with the remote fulfillment service.
GET/fetch_stock
Get inventory levels
max_retries |
The maximum amount of times Shopify will send the request for inventory levels. |
shop |
The shop's myshopify url. |
sku |
The SKU for the Product Variant we need stock levels for. |
timestamp |
The Unix timestamp from when the inventory request was made. |
Get inventory levels for a particular SKU.
https://myapp.com/fetch_stock.json?sku=123&shop=testshop.myshopify.com&max_retries=3×tamp=1532548742
{"123": 1000}
Get inventory levels for all SKUs.
https://myapp.com/fetch_stock.json?shop=testshop.myshopify.com
{"123": 1000, "456": 500}
Fulfillment webhooks
You can subscribe to the fulfillments/create
webhook to receive notifications about new fulfillments. The webhook fires every time an order is marked fulfilled
, and the data is sent to the registered URL.
After receiving and processing the webhook, your service should make a request to complete
the fulfillment. Before filling the order, check the fulfillment
service handle
on the fulfillment record to make sure that the fulfillment is in a pending
state.
You can also integrate the Fulfillment Service API to subscribe to the fulfillments/update
. The webhook fires every time a request comes in to get an update on a fulfillment.
For more information about webhooks, refer to our webhooks tutorial.
You can also update the fulfillment using the API with other information like tracking_numbers
rather than waiting for Shopify to ask for them.
View an open sourced Fulfillment Integration App that demonstrates how to use the Fulfillment API.
Setting fulfillments permissions
Add the write_fulfillments
permission to your requested scopes.
What you can do with FulfillmentService
The Shopify API lets you do the following with the FulfillmentService resource. More detailed versions of these general actions may be available:
- GET /admin/api/2021-04/fulfillment_services.json Receive a list of all FulfillmentServices
- POST /admin/api/2021-04/fulfillment_services.json Create a new FulfillmentService
- GET /admin/api/2021-04/fulfillment_services/{fulfillment_service_id}.json Receive a single FulfillmentService
- PUT /admin/api/2021-04/fulfillment_services/{fulfillment_service_id}.json Modify an existing FulfillmentService
- DELETE /admin/api/2021-04/fulfillment_services/{fulfillment_service_id}.json Remove an existing FulfillmentService
FulfillmentService properties
callback_url |
States the URL endpoint that Shopify needs to retrieve inventory and tracking updates. |
format |
Specifies the format of the API output. Valid values are json and xml. |
fulfillment_orders_opt_in |
Whether the fulfillment service wants to register for APIs related to fulfillment orders. To manage fulfillments using fulfillment orders, see Manage fulfillments with Fulfillment and FulfillmentOrder resources. |
handle |
A human-friendly unique string for the fulfillment service generated from its title. |
inventory_management |
States if the fulfillment service tracks product inventory and provides updates to Shopify. Valid values are "true" and "false". |
location_id |
The unique identifier of the location tied to the fulfillment service |
name |
The name of the fulfillment service as seen by merchants and their customers. |
provider_id |
A unique identifier for the fulfillment service provider. |
requires_shipping_method |
States if the fulfillment service requires products to be physically shipped. Valid values are "true" and "false". |
tracking_support |
States if the fulfillment service provides tracking numbers for packages. Valid values are "true" and "false". |
Endpoints
scope
|
|
List your app's fulfillment services
GET /admin/api/2021-04/fulfillment_services.json
View Response
HTTP/1.1 200 OK
{
"fulfillment_services": [
{
"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": 48752903,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
]
}
List all of the shop's fulfillment services
GET /admin/api/2021-04/fulfillment_services.json?scope=all
View Response
HTTP/1.1 200 OK
{
"fulfillment_services": [
{
"id": 61629186,
"name": "Venus Fulfillment",
"email": null,
"service_name": "Venus Fulfillment",
"handle": "venus-fulfillment",
"fulfillment_orders_opt_in": false,
"include_pending_stock": false,
"provider_id": null,
"location_id": 61629186,
"callback_url": null,
"tracking_support": true,
"inventory_management": 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": 48752903,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
]
}
To create a fulfillment service, you can also use a cURL request that uses that fulfillment_service.json
payload:
curl -X POST -d @fulfillment_service.json -H"Accept:application/json" -H"Content-Type:application/json" -H"X-Shopify-Access-Token:THE_TOKEN_GOES_HERE" https://AUTHORIZED_SHOP.myshopify.com/admin/fulfillment_services
Where THE_TOKEN_GOES_HERE
is replaced by the OAuth token given to you by Shopify and https://AUTHORIZED_SHOP.myshopify.com/admin/fulfillment_services
is replaced by the authorized shop's URL.
Create a fulfillment service
POST /admin/api/2021-04/fulfillment_services.json
{
"fulfillment_service": {
"name": "Jupiter Fulfillment",
"callback_url": "http://google.com",
"inventory_management": true,
"tracking_support": true,
"requires_shipping_method": true,
"format": "json"
}
}
View Response
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": false,
"include_pending_stock": false,
"provider_id": null,
"location_id": 1059367779,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
}
Get a single fulfillment service by its ID
GET /admin/api/2021-04/fulfillment_services/755357713.json
View Response
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": 48752903,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
}
Update a fulfillment service
PUT /admin/api/2021-04/fulfillment_services/755357713.json
{
"fulfillment_service": {
"id": 755357713,
"name": "New Fulfillment Service Name"
}
}
View Response
HTTP/1.1 200 OK
{
"fulfillment_service": {
"id": 755357713,
"name": "New Fulfillment Service Name",
"email": null,
"service_name": "New Fulfillment Service Name",
"handle": "new-fulfillment-service-name",
"fulfillment_orders_opt_in": true,
"include_pending_stock": false,
"provider_id": null,
"location_id": 48752903,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
}
Destroy a fulfillment service
DELETE /admin/api/2021-04/fulfillment_services/755357713.json
View Response
HTTP/1.1 200 OK
{
}
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 that fulfillment service.
Using the Fulfillment Service API, you can register, edit and delete a new fulfillment service.
When you register a new fulfillment service, you will need to expose the two following
GET endpoints rooted in the callback_url
:
fetch_tracking_numbers
: Where Shopify can retrieve tracking numbers for orders.fetch_stock
: Where Shopify can retrieve inventory levels.
Testing the GET endpoints
To make sure you have everything set up correctly, you can test the GET endpoints in your development store by completing the following steps:
- Install your app on a development store.
- Create a fulfillment service using an API request from the app.
- Create at least one product that uses the fulfillment service to manage its inventory (either in the Shopify admin or using the API).
A sample Shopify request for tracking numbers:
Once per hour Shopify will make a request to this endpoint if there are any completed fulfillments awaiting tracking numbers from the remote fulfillment service.
GET/fetch_tracking_numbers
Get tracking numbers for orders
order_names |
The fulfillment names we require tracking numbers for (i.e. #1001.1) |
shop |
The shop's myshopify url |
Get a list of tracking numbers for the following fulfillment names.
http://myapp.com/fetch_tracking_numbers.json?order_names[]=#1001.1&order_names[]=#1002.1&order_names[]=#1003.2
{ "tracking_numbers": { "#1001.1": "qwerty", "#1002.1": "asdfg", "#1003.2": "zxcvb" }, "message": "Successfully received the tracking numbers", "success": true }
A sample Shopify request for inventory levels:
Shopify will make a request for the inventory of an individual SKU when the product is set up initially, its SKU is changed in the Shopify admin, or its inventory management is set to use the fulfillment service. A request for all inventory data will happen once every hour to keep our system up to date with the remote fulfillment service.
GET/fetch_stock
Get inventory levels
max_retries |
The maximum amount of times Shopify will send the request for inventory levels. |
shop |
The shop's myshopify url. |
sku |
The SKU for the Product Variant we need stock levels for. |
timestamp |
The Unix timestamp from when the inventory request was made. |
Get inventory levels for a particular SKU.
https://myapp.com/fetch_stock.json?sku=123&shop=testshop.myshopify.com&max_retries=3×tamp=1532548742
{"123": 1000}
Get inventory levels for all SKUs.
https://myapp.com/fetch_stock.json?shop=testshop.myshopify.com
{"123": 1000, "456": 500}
Fulfillment webhooks
You can subscribe to the fulfillments/create
webhook to receive notifications about new fulfillments. The webhook fires every time an order is marked fulfilled
, and the data is sent to the registered URL.
After receiving and processing the webhook, your service should make a request to complete
the fulfillment. Before filling the order, check the fulfillment
service handle
on the fulfillment record to make sure that the fulfillment is in a pending
state.
You can also integrate the Fulfillment Service API to subscribe to the fulfillments/update
. The webhook fires every time a request comes in to get an update on a fulfillment.
For more information about webhooks, refer to our webhooks tutorial.
You can also update the fulfillment using the API with other information like tracking_numbers
rather than waiting for Shopify to ask for them.
View an open sourced Fulfillment Integration App that demonstrates how to use the Fulfillment API.
Setting fulfillments permissions
Add the write_fulfillments
permission to your requested scopes.
What you can do with FulfillmentService
The Shopify API lets you do the following with the FulfillmentService resource. More detailed versions of these general actions may be available:
- GET /admin/api/unstable/fulfillment_services.json Receive a list of all FulfillmentServices
- POST /admin/api/unstable/fulfillment_services.json Create a new FulfillmentService
- GET /admin/api/unstable/fulfillment_services/{fulfillment_service_id}.json Receive a single FulfillmentService
- PUT /admin/api/unstable/fulfillment_services/{fulfillment_service_id}.json Modify an existing FulfillmentService
- DELETE /admin/api/unstable/fulfillment_services/{fulfillment_service_id}.json Remove an existing FulfillmentService
FulfillmentService properties
callback_url |
States the URL endpoint that Shopify needs to retrieve inventory and tracking updates. |
format |
Specifies the format of the API output. Valid values are json and xml. |
fulfillment_orders_opt_in |
Whether the fulfillment service wants to register for APIs related to fulfillment orders. To manage fulfillments using fulfillment orders, see Manage fulfillments with Fulfillment and FulfillmentOrder resources. |
handle |
A human-friendly unique string for the fulfillment service generated from its title. |
inventory_management |
States if the fulfillment service tracks product inventory and provides updates to Shopify. Valid values are "true" and "false". |
location_id |
The unique identifier of the location tied to the fulfillment service |
name |
The name of the fulfillment service as seen by merchants and their customers. |
provider_id |
A unique identifier for the fulfillment service provider. |
requires_shipping_method |
States if the fulfillment service requires products to be physically shipped. Valid values are "true" and "false". |
tracking_support |
States if the fulfillment service provides tracking numbers for packages. Valid values are "true" and "false". |
Endpoints
scope
|
|
List your app's fulfillment services
GET /admin/api/unstable/fulfillment_services.json
View Response
HTTP/1.1 200 OK
{
"fulfillment_services": [
{
"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": 48752903,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
]
}
List all of the shop's fulfillment services
GET /admin/api/unstable/fulfillment_services.json?scope=all
View Response
HTTP/1.1 200 OK
{
"fulfillment_services": [
{
"id": 61629186,
"name": "Venus Fulfillment",
"email": null,
"service_name": "Venus Fulfillment",
"handle": "venus-fulfillment",
"fulfillment_orders_opt_in": false,
"include_pending_stock": false,
"provider_id": null,
"location_id": 61629186,
"callback_url": null,
"tracking_support": true,
"inventory_management": 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": 48752903,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
]
}
To create a fulfillment service, you can also use a cURL request that uses that fulfillment_service.json
payload:
curl -X POST -d @fulfillment_service.json -H"Accept:application/json" -H"Content-Type:application/json" -H"X-Shopify-Access-Token:THE_TOKEN_GOES_HERE" https://AUTHORIZED_SHOP.myshopify.com/admin/fulfillment_services
Where THE_TOKEN_GOES_HERE
is replaced by the OAuth token given to you by Shopify and https://AUTHORIZED_SHOP.myshopify.com/admin/fulfillment_services
is replaced by the authorized shop's URL.
Create a fulfillment service
POST /admin/api/unstable/fulfillment_services.json
{
"fulfillment_service": {
"name": "Jupiter Fulfillment",
"callback_url": "http://google.com",
"inventory_management": true,
"tracking_support": true,
"requires_shipping_method": true,
"format": "json"
}
}
View Response
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": false,
"include_pending_stock": false,
"provider_id": null,
"location_id": 1059367779,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
}
Get a single fulfillment service by its ID
GET /admin/api/unstable/fulfillment_services/755357713.json
View Response
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": 48752903,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
}
Update a fulfillment service
PUT /admin/api/unstable/fulfillment_services/755357713.json
{
"fulfillment_service": {
"id": 755357713,
"name": "New Fulfillment Service Name"
}
}
View Response
HTTP/1.1 200 OK
{
"fulfillment_service": {
"id": 755357713,
"name": "New Fulfillment Service Name",
"email": null,
"service_name": "New Fulfillment Service Name",
"handle": "new-fulfillment-service-name",
"fulfillment_orders_opt_in": true,
"include_pending_stock": false,
"provider_id": null,
"location_id": 48752903,
"callback_url": "http://google.com/",
"tracking_support": true,
"inventory_management": true
}
}
Destroy a fulfillment service
DELETE /admin/api/unstable/fulfillment_services/755357713.json
View Response
HTTP/1.1 200 OK
{
}