Legacy Order Management API Reference v3.2

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.

• List Orders
• Acknowledge Order
• Acknowledge Orders
• Attach Shipment
• Cancel Order
• Process Refund
• Transaction Details

Pagination

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.

Learn more about cursor-based pagination.

List Orders

List commerce orders associated with a Page.

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

Request

status_code enum

Sample Request

curl -X GET -G \
  -d 'updated_after=1529718360' \
  -d 'status="CREATED,IN_PROGRESS"' \
  -d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v24.0/<PAGE_ID>/commerce_orders

Response

order object

item object

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

order_status object

shipping_option object

shipping_address object

payment_details object

subtotal_details object

currency_amount object

estimated_shipping_time object

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.

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v24.0/<ORDER_ID>/acknowledge_order

Request

Sample Response

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

Acknowledge Orders

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/v24.0/<PAGE_ID>/acknowledge_orders

Request

order_id object

Sample Request

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

Response

order_id_and_status object

Sample Response

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

Attach Shipment

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

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v24.0/<ORDER_ID>/shipments

Request

shipment_item object

tracking_info object

carrier_code enum

The following is a list of common carrier codes:

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

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

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v24.0/<ORDER_ID>/cancel_order

Request

order_cancel_reason object

reason_code enum

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

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/v24.0/<ORDER_ID>/refund_order

Request

refund_item object

refund_reason_code enum

Sample request

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

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/v24.0/<PAGE_ID>/commerce_orders

Request

Response: Reimbursements

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

Reimbursement reason code enum

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.

Tax details object

Transaction type enum

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