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.

Shipments must include one and only one tracking number. For example, if you have an order with 2 items using 2 different tracking numbers, you make 2 API requests.

Graph API Explorer
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

Attribute & TypeDescription

external_shipment_id

Type: string

Optional

Unique external shipment ID representing a shipment as identified by the seller. Allowed characters are alphanumeric and _.

items

Type: array of items

Required

tracking_info

Type: tracking_info

Required

fulfillment

Type: fulfillment

Optional

idempotency_key

Type: string

Required

Unique key per request.

merchant_order_reference

Type: string

Optional

ID representing the order in your (seller) order management system. Added only if this ID was not updated during ACK call. If this ID differs from the existing merchant_order_reference ID, then the exception is returned.

items object

Attribute & TypeDescription

retailer_id

Type: string

Required if item_id is not provided.

ID representing the product in the seller's catalog. You must provide retailer_id or item_id, but not both. If item_id is provided, retailer_id must not be provided.

item_id

Type: string

Required if retailer_id is not provided.

A Meta-generated ID representing the line item on the order. This value is readable as the id field of the item response in the read. You must provide retailer_id or item_id, but not both. If retailer_id is provided, item_id must not be provided.

quantity

Type: number

Required

Number/quantity of items that are part of this shipment.

tracking_info object

Attribute & TypeType

carrier

Type: carrier_code

Required

Carrier used for this package.

tracking_number

Type: string

Required

Carrier tracking number.

shipping_method_name

Type: string

Optional

Human readable description of the shipping method.

fulfillment object

Attribute & TypeDescription

fulfillment_address

Type: fulfillment_address

Optional if fulfillment_location_id is provided; otherwise, Required.

Address of your fulfillment location from which the order is shipped for origin-based tax calculation.

fulfillment_location_id

Type: string

Optional if fulfillment_address is provided; otherwise, Required.

ID of the fulfillment location from which the order is shipped, previously set up in the Tax tab in your Commerce Manager. You can query the /{commerce-account-id}/tax_settings endpoint to pull all fulfillment locations set up in Commerce Manager.

fulfillment_location_id

Type: boolean (true/false)

Optional

Assign this field true if the seller's fulfillment address is the same as the one they added during onboard. If the seller assigns false, they need to provide alternative fulfillment address with the same API call.

fulfillment_address object

Attribute & TypeDescription

street_1

Type: string

Required

Street address of the fulfillment location.

street_2

Type: string

Optional

Second line of the address; typically the number of the apartment, suite, or unit.

city

Type: string

Required

City of the fulfillment location.

state

Type: string

Required

Two-letter state abbreviation. Example: NY.

country

Type: string

Required

Country of the fulfillment location.

postal_code

Type: string

Required

Postal code of the fulfillment location.

province_code

Type: string

Optional

Province of the fulfillment location.

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.

List Shipments

Fetch all shipments for a given order.

Graph API Explorer
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

Attribute & TypeDescription

data

Type: array of shipment

shipment object

Attribute & TypeDescriptionDefault

id

Type: string

Unique ID representing shipment.

Yes

external_shipment_id

Type: string

Unique external shipment ID representing a shipment as identified by the seller. Allowed characters are alphanumeric and _.

No

items

Type: data

Yes

tracking_info

Type: tracking_info

Yes

data object

Attribute & TypeDescription

data

Type: array of shipped_item

shipped_item object

Attribute & TypeDescription

id

Type: string

Unique ID representing the item as identified by Facebook.

retailer_id

Type: string

ID representing the product in the seller's catalog.

product_id

Type: string

ID representing the product in the Facebook catalog.

quantity

Type: number

Number of items ordered.

tax

Type: tax

tax object

Attribute & TypeDescription

final_tax

Type: currency_amount

currency_amount object

Attribute & TypeDescription

amount

Type: string

Amount in decimal format. Example: 5.5

currency

Type: string

Three digit ISO-4217-3 code for the purchase. Example: USD

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--"
    }
  }
}