Fulfillment API Reference

Use this API to manage shipments (including partial shipments) on a given order.

Attach a Shipment

Read this section to learn how to attach a shipment to a given order.

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/{order-id}/shipments

POST /{order-id}/shipments HTTP/1.1
Host: graph.facebook.com

/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->post(
    '/{order-id}/shipments',
    array (),
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */

/* make the API call */
FB.api(
    "/{order-id}/shipments",
    "POST",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

Request

items object

tracking_info object

fulfillment object

fulfillment_address object

carrier_code enum

Below is a list of common carrier codes:

• dhl
• dhl_ecommerce_us
• eagle
• fedex
• ontrac
• tnt
• ups
• usps

The full list of supported carrier codes is available here.

Sample Request

{
  "external_shipment_id": "external_shipment_1",
  "items": [
    {
      "retailer_id": "FB_product_1238",
      "quantity": 1
    },
    {
      "retailer_id": "FB_product_5624",
      "quantity": 2
    }
  ],
  "tracking_info": {
    "tracking_number": "ship 1",
    "carrier": "FEDEX",
    "shipping_method_name": "2 Day Fedex"
  },
  "fulfillment": {
    "fulfillment_location_id": "2153613121365"
  },
  "idempotency_key": "cb091e84-e75a-3a34-45d3-5153bec88b65"
}

Response

If successful:

{
  "success": true
}

Otherwise, a relevant error message is returned.

Update a Shipment

Update shipping tracking information set on a shipment. You can update shipments based on:

• External shipment ID
• Facebook shipment ID

Using an External Shipment ID

curl -X POST \
  -F `access_token=<ACCESS_TOKEN>` \
  https://graph.facebook.com/{order-id}/update_shipment

Request

Sample Request

{
   "external_shipment_id": "external_shipment_1",
   "tracking_info" : {
        "tracking_number": "12345abcd",
        "carrier": "FEDEX",
        "shipping_method_name": "2 Day Fedex"
    },
    "idempotency_key": "cb090e84-e75a-9a34-45d3-5153bec88b65"
}

Sample Response

If successful:

{
  "success": true
}

Otherwise, a relevant error message will be returned.

Using a Facebook Shipment ID

curl -X POST \
  -F `access_token=<ACCESS_TOKEN>` \
  https://graph.facebook.com/{order-id}/update_shipment

Request

Sample Request

{
   "shipment_id" : "45752147666494713", 
   "tracking_info" : {
        "tracking_number": "12345abcd",
        "carrier": "FEDEX",
        "shipping_method_name": "2 Day Fedex"
    },
    "idempotency_key": "cb090e84-e75a-9a34-45d3-5153bec88b65"
}

Sample Response

If successful:

{
  "success": true
}

Otherwise, a relevant error message will be returned.

List Shipments

Fetch all shipments for a given order.

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/{order-id}/shipments

GET /{order-id}/shipments HTTP/1.1
Host: graph.facebook.com

/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/{order-id}/shipments',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */

/* make the API call */
FB.api(
    "/{order-id}/shipments",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

Response

shipment object

data object

shipped_item object

tax object

currency_amount object

Sample Response

{
  "data": [
    {
      "id": "491193461614879",
      "items": {
        "data": [
          {
            "id": "486602442073981",
            "product_id": "2452389501475182",
            "retailer_id": "FB_shirt_1234",
            "quantity": 1,
            "tax": {
              "final_tax": {
                "amount": "0.04",
                "currency": "USD"
              }
            }
          }
        ]
      },
      "tracking_info": {
        "tracking_number": "ship 1",
        "carrier": "fedex"
      }
    }
  ],
  "paging": {
    "cursors": {
      "before": "--sanitized_key--",
      "after": "--sanitized_key--"
    }
  }
}