Legacy Order Management API Reference

This API is deprecated, and is provided for reference only. Please refer to the Order Management API (v3.3) 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 here.

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.

Pagination

In order to reliably retrieve all orders for all statuses, please 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.

Read more about cursor-based pagination here.

List Orders

List commerce orders associated with a Page. Note by default it will return orders only in CREATED state, unless status param is specified.

GET https://graph.facebook.com/vX.X/{page-id}/commerce_orders
access_token: PAGE_ACCESS_TOKEN

Request

AttributeTypeRequiredDescription

updated_after

string

Optional

Returns orders for which the status changed after this date in unix timestamp.

status

vector of status_code

Optional

Comma-separated list of statuses to filter on.

status_code enum

ValueDescription

FB_PROCESSING

This order is still being processed by Facebook. There is no action needed or possible on this order. This order may not advance to the CREATED state. FB_PROCESSING orders are for informative reasons only (i.e. to confirm to buyers that the order was placed).

CREATED

Order has been created on Facebook, not yet acknowledged by external merchants.

IN_PROGRESS

Order has been acknowledged, and now in progress.

SHIPPED

Order has been shipped.

CANCELLED

Order has been cancelled.

REFUNDED

Order has been refunded.

Sample Request

https://graph.facebook.com/vX.X/{page-id}/commerce_orders?updated_after=1529718360&status=CREATED%2CIN_PROGRESS

Response

AttributeTypeDescription

data

array of order

order object

AttributeTypeDescription

id

string

Unique ID representing the order. Although numerical, treat Order IDs as strings, as Order ID length and structure is subject to change.

email

string

Email address of the customer. For fulfillment purposes only, unless email_remarketing_option is set to true

email_remarketing_option

boolean

Customer's marketing opt-in status. Do not use email address for marketing purposes if set to false.

created

string

Order's creation datetime in ISO 8601 format.

last_updated

string

Order's latest update datetime in ISO 8601 format.

ship_by_date

string

The expected date the order is to be shipped by. Date format 'Y-m-d'

items

array of item

order_status

order_status

selected_shipping_option

shipping_option

Shipping option

selected for this order.

shipping_address

shipping_address

payment_details

payment_details

item object

The item object payload contains minimal details about the product itself. You can fetch additional product information by making the following Graph API call:

GET https://graph.facebook.com/vX.X/{fb_product_id}
AttributeTypeDescription

fb_product_id

string

Unique ID

representing the item. Multiple quantities of any item will be represented in the quantity field (see below).

retailer_id

string

ID representing the product in the merchant's catalog.

quantity

Number

Number of items ordered.

channel

string

Either facebook or instagram. Note: The channel field does not appear in the response by default. In order to see it, it must be queried for explicitly using ?fields= syntax. Learn more about reading Graph API fields.

price_per_unit

currency_amount

Unit price for this item.

calculated_tax

currency_amount

Tax amount for all items without shipping.

calculated_tax_rate

float

Tax rate in decimal format.

order_status object

AttributeTypeDescription

status_code

status_code

shipping_option object

AttributeTypeDescription

name

string

Human readable name of the shipping option.

price

currency_amount

Shipping cost.

calculated_tax

currency_amount

Shipping tax amount.

estimated_shipping_time

estimated_shipping_time

Estimated shipping time

shipping_address object

AttributeTypeDescription

name

string

Name on the shipping label.

street1

string

street2

string

city

string

state

string

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

postal_code

string

country

string

payment_details object

AttributeTypeDescription

subtotal

subtotal_details

Cost of items and shipping.

tax

currency_amount

Tax amount for the order.

total_amount

currency_amount

Total amount for the order.

tax_remitted

bool

true if taxes are collected by Facebook.

subtotal_details object

AttributeTypeDescription

items

currency_amount

Cost of products items in this order.

shipping

currency_amount

Shipping cost for the order.

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.

estimated_shipping_time object

AttributeTypeDescription

min_days

Number

Expected minimum number of days in shipping

max_days

Number

Expected maximum number of days in shipping

Sample Response

{
  "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 Order

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 merchants with higher order volumes will want to acknowledge orders every 5-15 minutes, as soon as they are read from the List Orders API.

POST https://graph.facebook.com/vX.X/{order-id}/acknowledge_order
access_token: PAGE_ACCESS_TOKEN

Request

AttributeTypeRequiredDescription

merchant_order_reference

string

Optional

ID representing the order in

your order management system.

Sample Response

{
  "id": "64000841784004",
  "status": "IN_PROGRESS"
}

Acknowledge Orders

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.

POST https://graph.facebook.com/vX.X/{page-id}/acknowledge_orders
access_token: PAGE_ACCESS_TOKEN

Request

AttributeTypeRequiredDescription

orders

array of order_id

Required

Array of 100 or less order IDs.

order_id object

AttributeTypeRequiredDescription

id

string

Required

ID of the order.

merchant_order_reference

string

Optional

ID representing the order in

your order management system

Sample Request

{
  "orders": [
    {
      "id": "64000841790004"
    },
    {
      "id": "10100677592885259"
    }
  ]
}

Response

AttributeTypeDescription

orders

array of order_id_and_status

order_id_and_status object

AttributeTypeDescription

id

string

ID of the order.

status

status_code

Sample Response

{
  "orders": [
    {
      "id": "64000841790004",
      "status": "IN_PROGRESS"
    },
    {
      "id": "10100677592885259",
      "error": {
        "error_code": 2361003,
        "error_message": "Invalid Order ID"
      }
    }
  ]
}

Attach Shipment

Merchant will use this API to update orders on Facebook side.

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

Request

AttributeTypeDescription

items

array of shipment_item

tracking_info

tracking_info

shipment_item 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.

carrier_code enum

The following is a list of common carrier codes:

Value

dhl

dhl_ecommerce_us

eagle

fedex

ontrac

tnt

ups

usps

See the full list of carrier codes here.

Sample Request

{
    "items" : [
        {
            "retailer_id" : "fb_tee_001",
            "quantity" : 3
        }
    ],
    "tracking_info" : {
        "tracking_number": "12345abcd",
        "carrier": "FEDEX", 
        "shipping_method_name": "2 Day Fedex"
    }
}

Response

If successful:

{
  "success": true
}

Otherwise a relevant error message will be returned.

Cancel Order

Merchant will use this API to cancel order on Facebook side.

POST https://graph.facebook.com/vX.X/{order-id}/cancel_order 
access_token: PAGE_ACCESS_TOKEN

Request

AttributeTypeRequiredDescription

order_cancel_reason

order_cancel_reason

Required

order_cancel_reason object

AttributeTypeRequiredDescription

reason_code

reason_code

Required

reason_description

string

Optional

Reason for the cancellation, this message may be presented to the user.

reason_code enum

ValueDescription

CUSTOMER_REQUESTED

OUT_OF_STOCK

INVALID_ADDRESS

SUSPICIOUS_ORDER

CANCEL_REASON_OTHER

Sample request

{
  "order_cancel_reason": {
    "reason_code": "CUSTOMER_REQUESTED",
    "reason_description": "Buyer did not need it anymore"
  }
}

Response

If successful:

{
  "success": true
}

Otherwise a relevant error message will be returned.

Process Refund

Merchant 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.

POST https://graph.facebook.com/vX.X/{order-id}/refund_order
access_token: PAGE_ACCESS_TOKEN
    

Request

AttributeTypeRequiredDescription

items

array of refund_item

Optional

For Partial refund specify item level breakdown, items are not required for full refunds.

reason_code

refund_reason_code

Required

reason_text

string

Optional

Reason for the refund. This message is presented to the user.

refund_item object

AttributeTypeRequiredDescription

retailer_id

string

Required

Retailer identifier for the product.

item_refund

currency_amount

Required

Cost of item, before any tax.

shipping_refund

currency_amount

Required

Amount to be refunded for shipping.

refund_reason_code enum

ValueDescription

BUYERS_REMORSE

DAMAGED_GOODS

NOT_AS_DESCRIBED

QUALITY_ISSUE

REFUND_REASON_OTHER

WRONG_ITEM

Sample request

Merchant will use this API to initiate a refund. Two kinds of refunds are supported

Partial/Item Level Refunds

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"
}

Full Refunds

{
  "reason_code": "WRONG_ITEM"
}

Response

If successful:

{
  "success": true
}

Otherwise a relevant error message will be returned.

Reimbursements and Transactions

After shipping or refunding an order, pull Reimbursement and Transaction information on orders to reconcile your transaction data.

GET https://graph.facebook.com/vX.X/{page-id}/commerce_orders?updated_after=1529718360&status=SHIPPED&fields=reimbursements,transaction_details{tax_rate,tax_details}

access_token: PAGE_ACCESS_TOKEN

Request

AttributeTypeRequiredDescription

updated_after

Unix timestamp

Required

Reimbursements and transactions will only display for orders after this timestamp.

status

Either SHIPPED or REFUNDED

Required

Order status for transaction request

fields

reimbursements, transaction_details{tax_rate,tax_details}

Required

Returns specified fields for reimbursements and transaction details

Response: Reimbursements

Reimbursements include any incentives applied, along with reason codes for the reimbursement.

ValueTypeDescription

reason

Reason code for the reimbursement

See Reason Codes below

value

currency_amount

Value of total reimbursement of this order

Reimbursement reason code enum

ValueDescription

INCENTIVE

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.

PAYOUT

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.

Response: Transaction details

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.

ValueTypeDescription

transaction_type

Reason code for the transaction

See Reason Codes below

transaction_date

ISO 8601 datetime

Datetime of transaction

processing_fee

object

Contains amount and currency objects consisting of the processing fee

net_payment_amount

object

Contains amount and currency objects consisting of the net payment amount

tax_rate

string

Percentage tax rate

tax_details

object

Tax details object

payout_reference_id

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.

Tax details object

ValueTypeDescription

tax_category

string

Facebook tax category

jurisdiction

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.

imposition

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.

item_tax_rate

string

Item level tax rate for the given category, jurisdiction and imposition. This gives the tax percentage for the given tax item detail row.

item_tax_amount

object

Item level tax amount calculated for this tax item row. This is calculated using the item tax rate provided above. Contains amount and currency fields.

Transaction type enum

ValueDescription

SALE

Indicates a normal SALE transaction when the money is captured from the buyer and transferred to the seller's balance

REFUND

Indicates that order is refunded and includes information on the refund itself

CHARGEBACK

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.

CHARGEBACK_FEE

Indicates the fee that was withheld if the seller loses in a chargeback claim.

CHARGEBACK_REVERSAL

Indicates that the seller won the chargeback claim and contains details on the chargeback being reversed

GOODWILL_TRANSFER

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.

Sample response

{
  "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"
    }
  ]
}