Ads and Commerce

Fulfillment API Reference

Updated: Dec 4, 2025
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 may 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.
curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<ORDER_ID>/shipments

Request

Attribute & Type Description
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
Optional
If omitted, all unfulfilled quantities of items on the order will be included in the shipment.
tracking_info
Type: tracking_info
Optional
While optional, Meta recommends including tracking information, when available, for an improved buyer experience.
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 & Type Description
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 & Type Type
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 & Type Description
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_address object

Attribute & Type Description
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.

Update a Shipment

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

Using an External Shipment ID

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

Request

Attribute & Type Description
external_shipment_id
Type: string
Required
ID representing a shipment as identified by the seller.
tracking_info
Type: tracking_info
Required
Status of shipment to track.
idempotency_key
Type: string
Required
Unique key per 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

Attribute & Type Description
shipment_id
Type: string
Required
ID representing a shipment as identified by Facebook.
tracking_info
Type: tracking_info
Required
Status of shipment to track.
idempotency_key
Type: string
Required
Unique key per 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/v25.0/<ORDER_ID>/shipments

Response

Attribute & Type Description
data
Type: array of shipment

shipment object

Attribute & Type Description Default
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 & Type Description
data
Type: array of shipped_item

shipped_item object

Attribute & Type Description
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 & Type Description
final_tax
Type: currency_amount

currency_amount object

Attribute & Type Description
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--"
    }
  }
}