Use this API to list orders, retrieve details about an order or products. In this section:
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/{cms-id}/commerce_orders
GET /{cms-id}/commerce_orders?fields=id%2Cbuyer_details%2Cchannel%2Cmerchant_order_id%2Corder_status 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(
'/{cms-id}/commerce_orders?fields=id%2Cbuyer_details%2Cchannel%2Cmerchant_order_id%2Corder_status',
'{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(
"/{cms-id}/commerce_orders",
{
"fields": "id,buyer_details,channel,merchant_order_id,order_status"
},
function (response) {
if (response && !response.error) {
/* handle the result */
}
}
);
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 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/{cms-id}/commerce_orders
GET /{cms-id}/commerce_orders 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(
'/{cms-id}/commerce_orders',
'{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(
"/{cms-id}/commerce_orders",
function (response) {
if (response && !response.error) {
/* handle the result */
}
}
);
Attribute | Type | Required | Description |
---|---|---|---|
|
| Optional | Returns orders for which the status changed before this date in unix timestamp. |
|
| Optional | Returns orders for which the status changed after this date in unix timestamp. |
|
| Optional | Comma-separated list of order states to filter on. When you specify two or more states behavior is OR. Defaults to |
|
| Optional | List of Comma-separated line item filters to fetch orders. When you specify two or more filters behavior is AND. Example fetch orders with filters |
order_state
State | Description |
---|---|
| Facebook is still processing this order. This order may not advance to the |
| Facebook 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. |
| Order 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. |
| All items present in the order are shipped and/or cancelled. |
order_filter
Filter | Description |
---|---|
| Get orders with line items that are not shipped yet. |
| Get orders with line items that are canceled. |
| Get orders that don't have any canceled line items. |
| Get orders with line items that have refunds. |
| Get orders that have no refunds. |
Attribute | Type | Description |
---|---|---|
|
| Returns only default order fields. Additional data can be queried by passing in as fields. |
order
objectAttribute | Type | Description | Default |
---|---|---|---|
|
| Unique ID representing the order. Although numerical, treat Order IDs as strings, as Order ID length and structure is subject to change. | Yes |
| Yes | ||
|
| Order's creation datetime in ISO 8601 format. | Yes |
|
| Order's latest update datetime in ISO 8601 format. | Yes |
| Items edge. Contains list of items purchased in this order | No | |
|
| The expected date the order is to be shipped by. Date format 'Y-m-d' | No |
|
| Unique ID representing the order in merchants Order Management System | No |
|
| Facebook or Instagram | No |
| This field is available for backward compatibility. Integrations should read the item level | No | |
| No | ||
| No | ||
| No |
order_status
objectAttribute | Type | Description |
---|---|---|
|
selected_shipping_option
objectAttribute | Type | Description |
---|---|---|
|
| Human readable name of the shipping option. |
| Shipping cost. | |
| Shipping tax amount. This amount is updated as the order is fulfilled, you can do additional API calls to update this amount. | |
| Estimated shipping time |
shipping_address
objectAttribute | Type | Description |
---|---|---|
|
| Name on the shipping label. |
|
| |
|
| |
|
| |
|
| Two-letter state abbreviation e.g. "NY" |
|
| |
|
|
estimated_payment_details
objectAttribute | Type | Description |
---|---|---|
| Sum of cost of items and shipping. | |
| Tax amount for the order. | |
| Total amount for the order. | |
|
|
|
| Total paid by Facebook-funded incentive. | |
| Total paid by the buyer. |
subtotal_details
objectAttribute | Type | Description |
---|---|---|
| Sum of cost of products items in this order. | |
| Shipping cost for the order. |
currency_amount
objectAttribute | Type | Description |
---|---|---|
|
| Amount in decimal format, eg. "5.5". |
|
| Three digit ISO-4217-3 code for the purchase, e.g. USD. |
estimated_shipping_time
objectAttribute | Type | Description |
---|---|---|
|
| Expected minimum number of days in shipping |
|
| Expected maximum number of days in shipping |
buyer_details
objectAttribute | Type | Description |
---|---|---|
|
| Name of the customer |
|
| Email address of the customer. For fulfillment purposes only, unless |
|
| Customer's marketing opt-in status. Do not use email address for marketing purposes if set to false. |
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/{cms-id}/commerce_orders
GET /{cms-id}/commerce_orders?fields=estimated_payment_details&updated_after=1529718360&state=CREATED&filters=no_shipments%2Cno_cancellations 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(
'/{cms-id}/commerce_orders?fields=estimated_payment_details&updated_after=1529718360&state=CREATED&filters=no_shipments%2Cno_cancellations',
'{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(
"/{cms-id}/commerce_orders",
{
"fields": "estimated_payment_details",
"updated_after": 1529718360,
"state": "CREATED",
"filters": "no_shipments,no_cancellations"
},
function (response) {
if (response && !response.error) {
/* handle the result */
}
}
);
{ "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--" } }
curl -X GET -G \
-d 'updated_before=1565728779' \
-d 'updated_after=1565555979' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/{cms-id}/commerce_orders
GET /{cms-id}/commerce_orders?updated_before=1565728779&updated_after=1565555979 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(
'/{cms-id}/commerce_orders?updated_before=1565728779&updated_after=1565555979',
'{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(
"/{cms-id}/commerce_orders",
{
"updated_before": 1565728779,
"updated_after": 1565555979
},
function (response) {
if (response && !response.error) {
/* handle the result */
}
}
);
{ "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--" } } }
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/{cms-id}/commerce_orders
GET /{cms-id}/commerce_orders?fields=id%2Corder_status%2Citems%2Cchannel&limit=1&state=CREATED 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(
'/{cms-id}/commerce_orders?fields=id%2Corder_status%2Citems%2Cchannel&limit=1&state=CREATED',
'{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(
"/{cms-id}/commerce_orders",
{
"fields": "id,order_status,items,channel",
"limit": 1,
"state": "CREATED"
},
function (response) {
if (response && !response.error) {
/* handle the result */
}
}
);
{ "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--" } } }
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/{order-id}
GET /{order-id} 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}',
'{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}",
function (response) {
if (response && !response.error) {
/* handle the result */
}
}
);
order
object with default fieldscurl -X GET -G \
-d 'fields="estimated_payment_details"' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/{order-id}
GET /{order-id}?fields=estimated_payment_details 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}?fields=estimated_payment_details',
'{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}",
{
"fields": "estimated_payment_details"
},
function (response) {
if (response && !response.error) {
/* handle the result */
}
}
);
{ "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" }
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/{order-id}/items
GET /{order-id}/items 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}/items',
'{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}/items",
function (response) {
if (response && !response.error) {
/* handle the result */
}
}
);
Attribute | Type | Description |
---|---|---|
|
|
item
objectAttribute | Type | Description | Default |
---|---|---|---|
|
| Unique ID representing the item. Multiple quantities of any item will be represented in the quantity field (see below). | Yes |
|
| ID representing the product in the merchant's catalog. | Yes |
|
| Name of Product. Note that this is not a default field and must be explicitly asked for via a | No |
|
| ID representing the product in the Facebook catalog. | Yes |
|
| Number of items ordered. | Yes |
| Selected shipping option | No | |
|
| Items status breakdown. For example: {"in_progress": 0, "fulfilled": 1, "cancelled": 1} | No |
| Unit price for this item. | Yes | |
| Tax details for this item. | No | |
|
| Text customization entered by the buyer on an order, if applicable. | No |
item_tax_details
ObjectAttribute | Type | Description |
---|---|---|
| This is total estimated tax for this particular item (all quantities), calculated during order creation by Facebook. This estimated tax never changes. | |
| This 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
ObjectAttribute | Type | Description |
---|---|---|
|
curl -X GET -G \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/{order-id}/items
GET /{order-id}/items 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}/items',
'{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}/items",
function (response) {
if (response && !response.error) {
/* handle the result */
}
}
);
{ "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--" } } }
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/{fb_product_id}
GET /{fb_product_id} 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(
'/{fb_product_id}',
'{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(
"/{fb_product_id}",
function (response) {
if (response && !response.error) {
/* handle the result */
}
}
);
Attribute | Type | Description | Default |
---|---|---|---|
|
| ID representing the product. | Yes |
|
| ID representing the product in the merchant's catalog. | Yes |
|
| Yes | |
|
| No | |
|
| No | |
|
| No | |
|
| No | |
|
| No | |
|
| No | |
|
| No | |
|
| No | |
|
| No | |
|
| No | |
|
| No | |
|
| No | |
|
| Current inventory level. | No |