This API is deprecated, and is provided for reference only. Please refer to the Order Management API moving forward.
After the user has completed the checkout flow and the payment transaction has been confirmed, the order will be made available for partners to manage. Order management consists of the following endpoints.
Access Tokens
The Order Management API relies on a Page Access Token to act as the Facebook Page. The Page Role behind the token must be EDITOR
or above. Learn more about page roles.
Be sure to retrieve orders for all statuses, to maintain parity between Facebook and your system. Facebook may need to CANCEL
orders from time to time due to fraud review.
To reliably retrieve all orders for all statuses, we recommend that you use cursor-based pagination. The default max limit of orders per page is 25.
Paging sizes may vary across statuses, and you may not get the same number of orders back per page.Learn more about cursor-based pagination.
List commerce orders associated with a Page.
By default, it returns orders only in the CREATED
state, unless the status
parameter is specified.
curl -X GET -G \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/{page-id}/commerce_orders
GET /{page-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(
'/{page-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(
"/{page-id}/commerce_orders",
function (response) {
if (response && !response.error) {
/* handle the result */
}
}
);
Attribute & Type | Description |
---|---|
Type: string | Optional Returns orders for which the status changed after this date in a UNIX timestamp. |
Type: vector of | Optional Comma-separated list of statuses to filter. |
status_code
enumValue | Description |
---|---|
| Order is still being processed by Facebook. |
| Order has been created on Facebook, not yet acknowledged by external sellers. |
| Order has been acknowledged, and now in progress. |
| Order has been shipped. |
| Order has been cancelled. |
| Order has been refunded. |
curl -X GET -G \
-d 'updated_after=1529718360' \
-d 'status="CREATED,IN_PROGRESS"' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/{page-id}/commerce_orders
GET /{page-id}/commerce_orders?updated_after=1529718360&status=CREATED%2CIN_PROGRESS 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(
'/{page-id}/commerce_orders?updated_after=1529718360&status=CREATED%2CIN_PROGRESS',
'{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(
"/{page-id}/commerce_orders",
{
"updated_after": 1529718360,
"status": "CREATED,IN_PROGRESS"
},
function (response) {
if (response && !response.error) {
/* handle the result */
}
}
);
Attribute & Type | Description |
---|
Type: array of |
order
objectAttribute & Type | Description |
---|---|
Type: string | Unique ID representing the order. Although numerical, manage order IDs as strings; order ID length and structure is subject to change. |
Type: string | Email address of the customer. Use for fulfillment purposes only, unless |
Type: boolean | Customer's marketing opt-in status. Do not use email address for marketing purposes if set to |
Type: string | Order's creation datetime in ISO 8601 format. |
Type: string | Order's latest update datetime in ISO 8601 format. |
Type: string | Expected date the order is to be shipped by. Date format: |
Type: array of | |
Type: array of | |
Type: array of | Shipping option selected for this order. |
Type: array of | |
Type: array of |
item
objectThe item
object payload contains minimal details about the product itself. You can fetch additional product information 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 |
---|---|---|
|
| Unique ID representing the item. Multiple quantities of any item will be represented in the quantity field (see below). |
|
| ID representing the product in the seller's catalog. |
|
| Number of items ordered. |
|
| Either |
| Unit price for this item. | |
| Tax amount for all items without shipping. | |
|
| Tax rate in decimal format. |
order_status
objectAttribute | Type | Description |
---|---|---|
|
shipping_option
objectAttribute | Type | Description |
---|---|---|
|
| Human readable name of the shipping option. |
| Shipping cost. | |
| Shipping tax amount. | |
| Estimated shipping time |
shipping_address
objectAttribute | Type | Description |
---|---|---|
|
| Name on the shipping label. |
|
| |
|
| |
|
| |
|
| Two-letter state abbreviation e.g. "NY" |
|
| |
|
|
payment_details
objectAttribute | Type | Description |
---|---|---|
| Cost of items and shipping. | |
| Tax amount for the order. | |
| Total amount for the order. | |
|
|
|
subtotal_details
objectAttribute | Type | Description |
---|---|---|
| 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 |
{ "data": [ { "items": [ { "fb_product_id": "1747144002010730", "retailer_id": "1522693943pages_commerce_sell5ac27737cc5fc7490521823", "quantity": 1, "price_per_unit": { "amount": "0.55", "currency": "USD" }, "calculated_tax": { "amount": "0.06", "currency": "USD" }, "calculated_tax_rate": 0.101 } ], "order_status": { "status_code": "IN_PROGRESS" }, "email": "user@example.com", "created": "2018-05-14T23:02:59+00:00", "last_updated": "2018-05-14T23:03:22+00:00", "ship_by_date": "2018-05-17", "payment_details": { "subtotal": { "items": { "amount": "0.55", "currency": "USD" }, "shipping": { "amount": "0.00", "currency": "USD" } }, "tax": { "amount": "0.06", "currency": "USD" }, "total_amount": { "amount": "0.61", "currency": "USD" }, "tax_remitted": true }, "selected_shipping_option": { "name": "STANDARD (3-5 Business days)", "price": { "amount": "0.00", "currency": "USD" }, "calculated_tax": { "amount": "0.00", "currency": "USD" }, "estimated_shipping_time": { "min_days": 5, "max_days": 7 } }, "shipping_address": { "name": "John Smith", "street1": "1101 Dexter Ave N", "city": "Seattle", "state": "WA", "postal_code": "98109-3517", "country": "US" }, "id": "64000782776004" } ] }
Acknowledge one specific order that was retrieved using the List Orders API. This marks the order on FB side as acknowledged, and can be filtered out from future pulls.
Some orders may not acknowledge on the first attempt. Be sure to capture errors, take action according to error messages, and retry accordingly. Do not start processing orders in your systems that have not been successfully acknowledged.
Orders need to be acknowledged 12 hours after they have been created or less. To avoid SLA breach please acknowledge orders at least 2x a day, preferably more frequently. Most sellers with higher order volumes will want to acknowledge orders every 5-15 minutes, as soon as they are read from the List Orders API.
curl -X POST \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/{order-id}/acknowledge_order
POST /{order-id}/acknowledge_order 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}/acknowledge_order',
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}/acknowledge_order",
"POST",
function (response) {
if (response && !response.error) {
/* handle the result */
}
}
);
Attribute | Type | Required | Description |
---|---|---|---|
|
| Optional | ID representing the order in your order management system. |
{ "id": "64000841784004", "status": "IN_PROGRESS" }
Acknowledge order batches have a maximum of 100 orders per batch.
Acknowledge any orders that were received by list orders api, in a batch. This marks the order on FB side as acknowledged. This reduces unacknowledged orders in any future pulls of the List API.
curl -X POST \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/{page-id}/acknowledge_orders
POST /{page-id}/acknowledge_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->post(
'/{page-id}/acknowledge_orders',
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(
"/{page-id}/acknowledge_orders",
"POST",
function (response) {
if (response && !response.error) {
/* handle the result */
}
}
);
Attribute | Type | Required | Description |
---|---|---|---|
|
| Required | Array of 100 or less order IDs. |
order_id
objectAttribute | Type | Required | Description |
---|---|---|---|
|
| Required | ID of the order. |
|
| Optional | ID representing the order in your order management system |
{ "orders": [ { "id": "64000841790004" }, { "id": "10100677592885259" } ] }
Attribute | Type | Description |
---|---|---|
|
|
order_id_and_status
objectAttribute | Type | Description |
---|---|---|
|
| ID of the order. |
|
{ "orders": [ { "id": "64000841790004", "status": "IN_PROGRESS" }, { "id": "10100677592885259", "error": { "error_code": 2361003, "error_message": "Invalid Order ID" } } ] }
Seller will use this API to update orders on Facebook side.
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 */
}
}
);
Attribute | Type | Description |
---|---|---|
|
| |
|
shipment_item
objectAttribute | Type | Required | Description |
---|---|---|---|
|
| Required | ID representing the product in the seller's catalog. |
|
| Required | Quantity. |
tracking_info
objectAttribute | Type | Required | Description |
---|---|---|---|
| Required | Carrier used for this package | |
|
| Required | Carrier tracking number |
|
| Optional | Human readable description of the shipping method. |
carrier_code
enumThe following is a list of common carrier codes:
Value |
---|
|
|
|
|
|
|
|
|
{ "items" : [ { "retailer_id" : "fb_tee_001", "quantity" : 3 } ], "tracking_info" : { "tracking_number": "12345abcd", "carrier": "FEDEX", "shipping_method_name": "2 Day Fedex" } }
If successful:
{ "success": true }
Otherwise a relevant error message will be returned.
Seller will use this API to cancel order on Facebook side.
curl -X POST \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/{order-id}/cancel_order
POST /{order-id}/cancel_order 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}/cancel_order',
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}/cancel_order",
"POST",
function (response) {
if (response && !response.error) {
/* handle the result */
}
}
);
Attribute | Type | Required | Description |
---|---|---|---|
| Required |
order_cancel_reason
objectAttribute | Type | Required | Description |
---|---|---|---|
| Required | ||
|
| Optional | Reason for the cancellation, this message may be presented to the user. |
reason_code
enumValue | Description |
---|---|
| |
| |
| |
| |
|
{ "order_cancel_reason": { "reason_code": "CUSTOMER_REQUESTED", "reason_description": "Buyer did not need it anymore" } }
If successful:
{ "success": true }
Otherwise a relevant error message will be returned.
Seller will use this API to initiate a refund. Two kinds of refunds are supported - Item level refund and full order refund. For a partial (by quantity or price) refund, use an item level refund. Refer Sample request for examples.
curl -X POST \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/{order-id}/refund_order
POST /{order-id}/refund_order 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}/refund_order',
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}/refund_order",
"POST",
function (response) {
if (response && !response.error) {
/* handle the result */
}
}
);
Attribute | Type | Required | Description |
---|---|---|---|
|
| Optional | For Partial refund specify item level breakdown, items are not required for full refunds. |
| Required | ||
|
| Optional | Reason for the refund. This message is presented to the user. |
refund_item
objectAttribute | Type | Required | Description |
---|---|---|---|
|
| Required | Retailer identifier for the product. |
| Required | Cost of item, before any tax. | |
| Required | Amount to be refunded for shipping. |
refund_reason_code
enumValue | Description |
---|---|
| |
| |
| |
| |
| |
|
Seller will use this API to initiate a refund. Two kinds of refunds are supported
The amount
field can be any value up to the full value of the item.
{ "items": [ { "retailer_id": "38383838", "item_refund": { "amount": "5.5", "currency": "USD" }, "shipping_refund": { "amount": "2.4", "currency": "USD" } } ], "reason_code": "WRONG_ITEM" }
{ "reason_code": "WRONG_ITEM" }
If successful:
{ "success": true }
Otherwise a relevant error message will be returned.
After shipping or refunding an order, pull Reimbursement and Transaction information on orders to reconcile your transaction data.
curl -X GET -G \
-d 'updated_after=1529718360' \
-d 'status="SHIPPED"' \
-d 'fields="reimbursements,transaction_details{tax_rate,tax_details}"' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/{page-id}/commerce_orders
GET /{page-id}/commerce_orders?updated_after=1529718360&status=SHIPPED&fields=reimbursements%2Ctransaction_details%7Btax_rate%2Ctax_details%7D 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(
'/{page-id}/commerce_orders?updated_after=1529718360&status=SHIPPED&fields=reimbursements%2Ctransaction_details%7Btax_rate%2Ctax_details%7D',
'{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(
"/{page-id}/commerce_orders",
{
"updated_after": 1529718360,
"status": "SHIPPED",
"fields": "reimbursements,transaction_details{tax_rate,tax_details}"
},
function (response) {
if (response && !response.error) {
/* handle the result */
}
}
);
Attribute | Type | Required | Description |
---|---|---|---|
| Unix timestamp | Required | Reimbursements and transactions will only display for orders after this timestamp. |
| Either | Required | Order status for transaction request |
|
| Required | Returns specified fields for reimbursements and transaction details |
Reimbursements include any incentives applied, along with reason codes for the reimbursement.
Value | Type | Description |
---|---|---|
| Reason code for the reimbursement | See Reason Codes below |
|
| Value of total reimbursement of this order |
reason
code enumValue | Description |
---|---|
| A reimbursement made by Facebook to the seller for a specific reason. The amount is added to the seller's reimbursement balance until it's paid out to the seller's bank account. |
| The bank transfer made to the seller's bank account which includes a set of reimbursements. Includes details on when the payout was initiated and the amount that was transferred to the seller's bank account. Payout rows are included in the report after the 3 day delay from when the payout was actually initiated. |
List of orders and all transaction associated with each order. This list will contain only those orders which had a transaction after updated_after
timestamp.
Value | Type | Description |
---|---|---|
| Reason code for the transaction | See Reason Codes below |
| ISO 8601 datetime | Datetime of transaction |
| object | Contains |
| object | Contains |
| string | Percentage tax rate |
| object | Tax details object |
| string | The bank reference ID associated with the payout in which this transaction is included. Note: only available for payouts processed after 5/15/19. |
Value | Type | Description |
---|---|---|
| string | Facebook tax category |
| string | The Jurisdiction under which tax is applied. Jurisdiction can be a state (e.g. Washington), city (e.g. Seattle), county(e.g. King county) or even a specific tax policy (e.g. Regional Transit Authority). Indicates under which jurisdiction the tax was found to be required for the given transaction. |
| string | Type of imposition for the tax item, indicating what type of tax this is. For example, “Local Sales and Use Tax” and “Retail Sales and Use Tax” are common imposition values. |
| string | Item level tax rate for the given category, jurisdiction and imposition. This gives the tax percentage for the given tax item detail row. |
| object | Item level tax amount calculated for this tax item row. This is calculated using the item tax rate provided above. Contains |
Value | Description |
---|---|
| Indicates a normal SALE transaction when the money is captured from the buyer and transferred to the seller's balance |
| Indicates that order is refunded and includes information on the refund itself |
| Indicates that there was a chargeback filed by the buyer for this order. Usually, this type of transaction will be followed by a CHARGEBACK_FEE transaction if the seller loses the chargeback claim. If the seller wins the chargeback claim, this will be followed by a CHARGEBACK_REVERSAL transaction. |
| Indicates the fee that was withheld if the seller loses in a chargeback claim. |
| Indicates that the seller won the chargeback claim and contains details on the chargeback being reversed |
| Goodwill transfer details that Facebook paid the seller. This can happen if Facebook covers the chargeback, or in other cases where Facebook pays the seller for their loss, such as the seller winning an appeal against a buyer protection claim from the buyer. |
{ "data": [ { "reimbursements": { "data": [ { "reason": "FREE_SHIPPING", "value": { "amount": "0.06", "currency": "USD" } }, { "reason": "FLAT_BUYER_DISCOUNT", "value": { "amount": "0.06", "currency": "USD" } } ] }, "transaction_details": { "data": [ { "transaction_type": "SALE", "transaction_date": "2019-01-09T09:16:21+00:00", "processing_fee": { "amount": "-0.05", "currency": "USD", }, "net_payment_amount": { "amount": "0.55", "currency": "USD", }, "tax_rate": "10%", "tax_details": { "data": [ { "tax_category": "FBMP_OTHER_TAXABLE", "jurisdiction": "WASHINGTON", "imposition": "Retail Sales and Use Tax", "item_tax_rate": "6.50%", "item_tax_amount": { "amount": "0.08", "currency": "USD" } } ] }, "payout_reference_id": "FBMPUSS5191u01g" } ] }, "id": "64000782776004" } ] }