Meta / Facebook Developer Docs Mirror

Appearance

Mirrored from https://developers.facebook.com/documentation/ads-commerce/commerce-platform/order-management/acknowledgement-api

Order API Reference ​

Updated: Feb 9, 2026

Use this API to list orders, retrieve details about an order or products. In this section:

Fields ​

When you query the Order API, by default it will return a set of fields: id, order_status, created and last_updated.

However, you can specify which fields you want returned by using the fields parameter and listing each field. This overrides the defaults and returns only the fields you specify, and the ID of the object, which is always returned.

All fields marked as non-default should explicitly be added to the fields parameter in the request.

For example, if you wanted to get all orders and only see the fields: id, buyer_details, channel, merchant_order_id, order_status you would make the following call:

curl -X GET -G \
  -d 'fields="id,buyer_details,channel,merchant_order_id,order_status"' \
  -d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<CMS_ID>/commerce_orders

This query would return the following response:

{
  "data": [
    {
      "id": "368508827392800",
      "buyer_details": {
        "name": "John Smith",
        "email": "n8miblde3i@marketplace.facebook.com",
        "email_remarketing_option": false
      },
      "channel": "facebook",
      "order_status": {
        "state": "CREATED"
      }
    }
  ],
  "paging": {
    "cursors": {
      "before": "QVFIUkxqeHRvVTN0OXpSWWE4X3FwVkRtUkxobkYtWlVGN0FQbVpVZAFE4VEpzOTFvNzhpcGV2QzhxX25ZAWkE2YWNVdkZA6UWprY3JhTmRrOGpiZA3ZA3MnEtU01n",
      "after": "QVFIUkxqeHRvVTN0OXpSWWE4X3FwVkRtUkxobkYtWlVGN0FQbVpVZAFE4VEpzOTFvNzhpcGV2QzhxX25ZAWkE2YWNVdkZA6UWprY3JhTmRrOGpiZA3ZA3MnEtU01n"
    }
  }
}

To find out more information on fields and how to use them, check out to Graph API documentation on this topic.

List Orders ​

List all the commerce orders associated with a Shop. By default this endpoint returns orders in CREATED state unless state parameter is specified. The response only returns default fields, unless you request additional fields explicitly. Refer to the samples for more information.

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<CMS_ID>/commerce_orders

Request ​

AttributeTypeRequiredDescription
updated_beforestringOptionalReturns orders for which the status changed before this date in unix timestamp.
updated_afterstringOptionalReturns orders for which the status changed after this date in unix timestamp.
statevector of order_stateOptionalComma-separated list of order states to filter on. When you specify two or more states behavior is OR. Defaults to CREATED if not specified.
filtersvector of filter_codeOptionalList of Comma-separated line item filters to fetch orders. When you specify two or more filters behavior is AND. Example fetch orders with filters no_shipments AND no_cancellations

order_state ​

StateDescription
FB_PROCESSINGFacebook is still processing this order. This order may not advance to the CREATED state if canceled by buyer or Facebook for fraud. See best practices on handling orders in this state.
CREATEDFacebook has finalized the order, the seller needs to acknowledge the order to be able to act on the order. The seller can get the orders and acknowledge.
IN_PROGRESSOrder is acknowledged and moved into your order management service. This state indicates that seller has to yet ship some or all items related to order.
COMPLETEDAll items present in the order are shipped and/or cancelled.

order_filter ​

FilterDescription
no_shipmentsGet orders with line items that are not shipped yet.
has_cancellationsGet orders with line items that are canceled.
no_cancellationsGet orders that don't have any canceled line items.
has_refundsGet orders with line items that have refunds.
no_refundsGet orders that have no refunds.

Response ​

AttributeTypeDescription
dataarray of orderReturns only default order fields. Additional data can be queried by passing in as fields.

order object ​

AttributeTypeDescriptionDefault
idstringUnique ID representing the order. Although numerical, treat Order IDs as strings, as Order ID length and structure is subject to change.Yes
order_statusorder_statusYes
createdstringOrder's creation datetime in ISO 8601 format⁠.Yes
last_updatedstringOrder's latest update datetime in ISO 8601 format⁠.Yes
itemsitems objectItems edge. Contains list of items purchased in this orderNo
ship_by_datestringThe expected date the order is to be shipped by. Date format 'Y-m-d'No
merchant_order_idstringUnique ID representing the order in merchants Order Management SystemNo
channelstringFacebook or InstagramNo
selected_shipping_optionselected_shipping_optionThis field is available for backward compatibility. Integrations should read the item level selected_shipping_optionNo
shipping_addressshipping_addressNo
estimated_payment_detailsestimated_payment_detailsNo
buyer_detailsbuyer_detailsNo

order_status object ​

AttributeTypeDescription
stateorder_state

selected_shipping_option object ​

AttributeTypeDescription
namestringHuman readable name of the shipping option.
pricecurrency_amountShipping cost.
calculated_taxcurrency_amountShipping tax amount. This amount is updated as the order is fulfilled, you can do additional API calls to update this amount.
estimated_shipping_timeestimated_shipping_timeEstimated shipping time

shipping_address object ​

AttributeTypeDescription
namestringName on the shipping label.
street1string
street2string
citystring
statestringTwo-letter state abbreviation e.g. "NY"
postal_codestring
countrystring

estimated_payment_details object ​

AttributeTypeDescription
subtotalsubtotal_detailsSum of cost of items and shipping.
taxcurrency_amountTax amount for the order.
total_amountcurrency_amountTotal amount for the order.
tax_remittedbooltrue if taxes are collected by Facebook.
facebook_paid_amountcurrency_amountTotal paid by Facebook-funded incentive.
buyer_paid_amountcurrency_amountTotal paid by the buyer.

subtotal_details object ​

AttributeTypeDescription
itemscurrency_amountSum of cost of products items in this order.
shippingcurrency_amountShipping cost for the order.

currency_amount object ​

AttributeTypeDescription
amountstringAmount in decimal format, eg. "5.5".
currencystringThree digit ISO-4217-3 code for the purchase, e.g. USD.

estimated_shipping_time object ​

AttributeTypeDescription
min_daysNumberExpected minimum number of days in shipping
max_daysNumberExpected maximum number of days in shipping

buyer_details object ​

AttributeTypeDescription
namestringName of the customer
emailstringEmail address of the customer. For fulfillment purposes only, unless email_remarketing_option is set to true
email_remarketing_optionbooleanCustomer's marketing opt-in status. Do not use email address for marketing purposes if set to false.

Sample Request (default fields) ​

  • Get Orders with status CREATED and filters with no shipments AND no cancellations with default fields in the response.
curl -X GET -G \
  -d 'fields="estimated_payment_details"' \
  -d 'updated_after=1529718360' \
  -d 'state="CREATED"' \
  -d 'filters="no_shipments,no_cancellations"' \
  -d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<CMS_ID>/commerce_orders

Sample Response (default fields) ​

{  
  "data": [  
    {  
      "id": "335211597203390",  
      "order_status": {  
        "state": "CREATED"  
      },  
      "created": "2019-01-14T19:17:31+00:00",  
      "last_updated": "2019-01-14T19:47:35+00:00"  
    },  
    {  
      "id": "2247696628885631",  
      "order_status": {  
        "state": "CREATED"  
      },  
      "created": "2019-01-11T22:56:04+00:00",  
      "last_updated": "2019-01-11T23:26:18+00:00"  
    },  
    {  
      "id": "64000005580968",  
      "order_status": {  
        "state": "CREATED"  
      },  
      "created": "2018-09-27T04:25:57+00:00",  
      "last_updated": "2018-09-27T04:26:14+00:00"  
    },  
    // ... 25 more orders if present  
  ],  
  "paging": {  
    "cursors": {  
      "before": "--sanitized_key--",  
      "after": "--sanitized_key--"  
    },  
    "next": "https://graph.facebook.com/vX.X/<cms-id>/commerce_orders?access_token=--sanitized_key--&pretty=0&limit=25&after=--sanitized_key--"  
  }  
}

Sample Request to fetch orders between two dates (default fields) ​

  • Get Orders between dates by using updated_after and updated_before
curl -X GET -G \
  -d 'updated_before=1565728779' \
  -d 'updated_after=1565555979' \
  -d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<CMS_ID>/commerce_orders

Sample Response ​

 {  
  "data": [  
    {  
      "id": "1299096923600598",  
      "order_status": {  
        "state": "CREATED"  
      },  
      "created": "2019-08-12T20:45:32+00:00",  
      "last_updated": "2019-08-12T20:45:42+00:00"  
    },  
    {  
      "id": "388309381882686",  
      "order_status": {  
        "state": "CREATED"  
      },  
      "created": "2019-08-12T19:52:46+00:00",  
      "last_updated": "2019-08-12T19:52:56+00:00"  
    },  
    {  
      "id": "366654374253443",  
      "order_status": {  
        "state": "CREATED"  
      },  
      "created": "2019-08-12T19:52:09+00:00",  
      "last_updated": "2019-08-12T19:52:19+00:00"  
    }  
  ],  
  "paging": {  
    "cursors": {  
      "before": "--sanitized_key--",  
      "after": "--sanitized_key--"  
    }  
  }  
}

Sample Request (multi-item order) ​

  • Get multi-item Orders with additional fields and filters
curl -X GET -G \
  -d 'fields="id,order_status,items,channel"' \
  -d 'limit=1' \
  -d 'state="CREATED"' \
  -d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<CMS_ID>/commerce_orders

Sample Response (multi-item order) ​

{  
  "data": [  
    {  
      "id": "372892946712291",  
      "order_status": {  
        "state": "CREATED"  
      },  
      "items": {  
        "data": [  
          {  
            "id": "372892953378957",  
            "product_id": "2416339625125194",  
            "retailer_id": "FB_product_1237",  
            "quantity": 1,  
            "price_per_unit": {  
              "amount": "0.99",  
              "currency": "USD"  
            }  
          },  
          {  
            "id": "372892943378958",  
            "product_id": "2654057021279988",  
            "retailer_id": "FB_product_1238",  
            "quantity": 1,  
            "price_per_unit": {  
              "amount": "0.99",  
              "currency": "USD"  
            }  
          }  
        ],  
        "paging": {  
          "cursors": {  
            "before": "--sanitized_key--",  
            "after": "--sanitized_key--"  
          }  
        }  
      },  
      "channel": "instagram"  
    }  
  ],  
  "paging": {  
    "cursors": {  
      "before": "--sanitized_key--",  
      "after": "--sanitized_key--"  
    }  
  }  
}

Get Order Details ​

Fetch order details for a given Facebook Order ID. The response only returns default fields, unless you request additional fields explicitly.

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<ORDER_ID>

Response ​

  • order object with default fields

Sample Request ​

  • Get Order details with additional fields
curl -X GET -G \
  -d 'fields="estimated_payment_details"' \
  -d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<ORDER_ID>

Sample Response ​

{  
  "estimated_payment_details": {  
    "subtotal": {  
      "items": {  
        "amount": "2.00",  
        "currency": "USD"  
      },  
      "shipping": {  
        "amount": "0.00",  
        "currency": "USD"  
      }  
    },  
    "tax": {  
      "amount": "0.19",  
      "currency": "USD"  
    },  
    "total_amount": {  
      "amount": "2.19",  
      "currency": "USD"  
    },  
    "tax_remitted": true  
  },  
  "id": "412336950726541"  
}

List Order Items ​

Fetch line items for a given Facebook Order ID. The response only returns default fields, unless you request additional fields explicitly.

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<ORDER_ID>/items

Response ​

AttributeTypeDescription
dataarray of item

item object ​

AttributeTypeDescriptionDefault
idstringUnique ID representing the item. Multiple quantities of any item will be represented in the quantity field (see below).Yes
retailer_idstringID representing the product in the merchant's catalog.Yes
product_namestringName of Product. Note that this is not a default field and must be explicitly asked for via a fields= query.No
product_idstringID representing the product in the Facebook catalog.Yes
quantityNumberNumber of items ordered.Yes
selected_shipping_optionselected_shipping_optionSelected shipping optionNo
statusstringItems status breakdown. For example: {"in_progress": 0, "fulfilled": 1, "cancelled": 1}No
price_per_unitcurrency_amountUnit price for this item.Yes
tax_detailsitem_tax_detailsTax details for this item.No
customizationstringText customization entered by the buyer on an order, if applicable.No

item_tax_details Object ​

AttributeTypeDescription
estimated_taxcurrency_amountThis is total estimated tax for this particular item (all quantities), calculated during order creation by Facebook. This estimated tax never changes.
captured_taxtotal_taxThis represents the original tax collected on items that are fulfilled. This number will be updated based on shipments fulfilled. For Example: If an order has ten quantity of an item and estimated tax is $2.50 when the first shipment is made with 1 item, then capture_tax would be $0.25. Then merchant cancels five items and ships four items then capture_tax would be $1.21 (previous 1 item 0.25+0.24*4 items). capture_tax varies based on fulfillments, and price can be different based on fulfillment location. The capture_tax amount may differ from the estimated_tax amount by a few cents.

total_tax Object ​

AttributeTypeDescription
total_taxcurrency_amount

Sample Request ​

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<ORDER_ID>/items

Sample Response ​

{  
  "data": [  
    {  
      "id": "2082596341811586",  
      "product_id": "1213131231",  
      "retailer_id": "external_product_1234",  
      "quantity": 2,  
      "price_per_unit": {  
        "amount": "20.00",  
        "currency": "USD"  
      }  
  
     "tax_details": {  
                "estimated_tax": {  
                  "amount": "0.30",  
                  "currency": "USD"  
                },  
                "captured_tax": {  
                  "total_tax": {  
                    "amount": "0.30",  
                    "currency": "USD"  
                  }  
               }  
           }  
    }  
  ],  
  "paging": {  
    "cursors": {  
      "before": "--sanitized_key--",  
      "after": "--sanitized_key--"  
    }  
  }  
}

Get Product Details ​

You can fetch additional details about a given product by making the following Graph API call:

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<PRODUCT_ID>

Response ​

AttributeTypeDescriptionDefault
idstringID representing the product.Yes
retailer_idstringID representing the product in the merchant's catalog.Yes
namestringYes
descriptionstringNo
brandstringNo
gtinstringNo
manufacturer_part_numberstringNo
colorstringNo
sizestringNo
genderstringNo
additional_variant_attributesarray of stringNo
urlstringNo
image_urlstringNo
visibilitystringNo
availabilitystringNo
inventoryNumberCurrent inventory level.No

Unofficial mirror for reference/search purposes. All content originates from developers.facebook.com — see the source link at the top of each page. Machine-readable indexes: llms.txt · llms-full.txt · About

Content © Meta Platforms, Inc. · Built by Arjun Aditya