Fulfillment API Reference

Use this API to manage shipments on a given order. In this section:

Attach a Shipment

Attach a shipment to a given order.

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

POST https://graph.facebook.com/vX.X/{order-id}/shipments?access_token={PAGE_ACCESS}

Request

AttributeTypeRequiredDescription

external_shipment_id

string

Optional

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

items

array of items

Required

tracking_info

tracking_info

Required

fulfillment

fulfillment

Optional

idempotency_key

string

Required

A unique key per request

merchant_order_reference

string

Optional

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

items object

AttributeTypeRequiredDescription

retailer_id

string

Required

ID representing the product in the merchant's catalog.

quantity

number

Required

Quantity.

tracking_info object

AttributeTypeRequiredDescription

carrier

carrier_code

Required

Carrier used for this package

tracking_number

string

Required

Carrier tracking number

shipping_method_name

string

Optional

Human readable description of the shipping method.

fulfillment object

AttributeTypeRequiredDescription

fulfillment_address

fulfillment_address

Optional if fulfillment_location_id is provided. Required otherwise.

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

fulfillment_location_id

string

Optional if fulfillment_address is provided. Required otherwise.

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_address object

AttributeTypeDescription

street1

string

street2

string

city

string

state

string

Two-letter state abbreviation e.g. "NY"

postal_code

string

country

string

carrier_code enum

Below is a list of common carrier codes. The full list of supported carrier codes is available here.

Value

dhl

dhl_ecommerce_us

eagle

fedex

ontrac

tnt

ups

usps

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 will be returned.

List Shipments

Fetch all shipments for a given order.

GET https://graph.facebook.com/vX.X/{order-id}/shipments?access_token={PAGE_ACCESS_TOKEN}

Response

AttributeTypeDescription

data

array of shipment

shipment object

AttributeTypeDescription Default

id

string

Unique ID representing shipment

Yes

external_shipment_id

string

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

No

items

data

Yes

shipping

shipping

No

tracking_info

tracking_info

Yes

data object

AttributeTypeDescription

data

array of shipped_item

shipped_item object

AttributeTypeDescription

id

string

Unique ID representing the item as identified by Facebook.

retailer_id

string

ID representing the product in the merchant's catalog.

product_id

string

ID representing the product in the Facebook catalog.

quantity

Number

Number of items ordered.

tax

tax

shipping object

AttributeTypeDescription

tax

tax

tax object

AttributeTypeDescription

final_tax

currency_amount

currency_amount object

AttributeTypeDescription

amount

string

Amount in decimal format, eg. "5.5".

currency

string

Three digit ISO-4217-3 code for the purchase, e.g. 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--"
    }
  }
}