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 Webgistix.

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.

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 order names we require tracking numbers for (i.e. #1001)

shop

The shop's myshopify url

Get a list of tracking numbers for the following order IDs.

http://myapp.com/fetch_tracking_numbers.json?order_names[]=#1001&order_names[]=#1002&order_names[]=#1003
                  { "tracking_numbers": {
                      "#1001": "qwerty",
                      "#1002": "asdfg",
                      "#1003": "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 or is changed in the Shop's Admin. 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

sku

The SKU for the Product Variant we need stock levels for

shop

The shop's myshopify url

Get inventory levels for a particular SKU.

https://myapp.com/fetch_stock.json?sku=123&shop=testshop.myshopify.com
                  {"123": 1000}
                

Get inventory levels for all SKUs.

https://myapp.com/fetch_stock.json?shop=testshop.myshopify.com
                  {"123": 1000,
                   "456": 500}
                

In order to be notified about new fulfillments you should subscribe your application to the fulfillments/create webhook. This webhook fires every time an order is marked "fulfilled", and the data is sent to a URL that you registered and stored in JSON format. You can read more about webhooks here. After receiving and processing the webhook your service should make a request to "complete" the fulfillment. You can also update the fulfillment via the API with other information like tracking_numbers rather than waiting for Shopify to ask for them.

You can also integrate the Fulfillment Service API to subscribe to the fulfillments/update. This webhook fires every time a request comes in to get an update on a fulfillment.

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 can you 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:

FulfillmentService Properties

callback_url
{ "callback_url" : "http://myapp.com" }

States the URL endpoint that Shopify needs to retrieve inventory and tracking updates. This field is necessary if either inventory_management or tracking_support is set to "true".

format
{ "format" : "json" }

Specifies the format of the API output. Valid values are json and xml.

handle
{ "handle" : "my_fulfillment_service" }

A human-friendly unique string for the fulfillment service generated from its title.

inventory_management
{ "inventory_management" : true }

States if the fulfillment service tracks product inventory and provides updates to Shopify. Valid values are "true" and "false".

name
{ "name" : "My Fulfillment Service" }

The name of the fulfillment service as seen by merchants and their customers.

provider_id
{ "provider_id" : null }

A unique identifier for the fulfillment service provider.

requires_shipping_method
{ "requires_shipping_method" : true }

States if the fulfillment service requires products to be physically shipped. Valid values are "true" and "false".

tracking_support
{ "tracking_support" : true }

States if the fulfillment service provides tracking numbers for packages. Valid values are "true" and "false".

Endpoints

GET /admin/fulfillment_services.json
scope
  • 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

GET /admin/fulfillment_services.json
View Response
HTTP/1.1 200 OK
{
  "fulfillment_services": [
    {
      "id": 755357713,
      "name": "Shipwire App",
      "handle": "shipwire-app",
      "email": null,
      "include_pending_stock": false,
      "requires_shipping_method": false,
      "service_name": "Shipwire App",
      "inventory_management": true,
      "tracking_support": true,
      "provider_id": null
    }
  ]
}

List all of the shop's fulfillment services

GET /admin/fulfillment_services.json?scope=all
View Response
HTTP/1.1 200 OK
{
  "fulfillment_services": [
    {
      "id": 61629186,
      "name": "shipwire",
      "handle": "shipwire",
      "email": null,
      "include_pending_stock": false,
      "service_name": "Shipwire",
      "inventory_management": true,
      "tracking_support": true,
      "provider_id": 1
    },
    {
      "id": 755357713,
      "name": "Shipwire App",
      "handle": "shipwire-app",
      "email": null,
      "include_pending_stock": false,
      "requires_shipping_method": false,
      "service_name": "Shipwire App",
      "inventory_management": true,
      "tracking_support": true,
      "provider_id": null
    }
  ]
}
POST /admin/fulfillment_services.json

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/fulfillment_services.json
{
  "fulfillment_service": {
    "name": "MarsFulfillment",
    "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": "MarsFulfillment",
    "handle": "marsfulfillment",
    "email": null,
    "include_pending_stock": false,
    "requires_shipping_method": true,
    "service_name": "Mars Fulfillment",
    "inventory_management": true,
    "tracking_support": true,
    "provider_id": null
  }
}
GET /admin/fulfillment_services/755357713.json

Get a single fulfillment service by its ID

GET /admin/fulfillment_services/#{id}.json
View Response
HTTP/1.1 200 OK
{
  "fulfillment_service": {
    "id": 755357713,
    "name": "Shipwire App",
    "handle": "shipwire-app",
    "email": null,
    "include_pending_stock": false,
    "requires_shipping_method": false,
    "service_name": "Shipwire App",
    "inventory_management": true,
    "tracking_support": true,
    "provider_id": null
  }
}
PUT /admin/fulfillment_services/755357713.json

Update a fulfillment service

PUT /admin/fulfillment_services/#{id}.json
{
  "fulfillment_service": {
    "id": 755357713,
    "inventory_management": false
  }
}
View Response
HTTP/1.1 200 OK
{
  "fulfillment_service": {
    "id": 755357713,
    "name": "Shipwire App",
    "handle": "shipwire-app",
    "email": null,
    "include_pending_stock": false,
    "requires_shipping_method": false,
    "service_name": "Shipwire App",
    "inventory_management": false,
    "tracking_support": true,
    "provider_id": null
  }
}
DELETE /admin/fulfillment_services/755357713.json

Destroy a fulfillment service

DELETE /admin/fulfillment_services/#{id}.json
View Response
HTTP/1.1 200 OK
{}