Order Snapshot API

Updated: Aug 8, 2024

Copy for LLM

Use this API to provide the most recent snapshot of an order and update it on Shops.

Before You Begin

While Meta offers many APIs to manage orders and shops, some sellers may benefit from a simpler integration depending on how their Order Management System (OMS) works. The Order Snapshot API is ideal for an OMS that is able to provide full, item-level order details without regard for what has “changed.” The API is also singular, compared to the several Order Management APIs that would be required to integrate in an event-based setup.

Please review the Meta Commerce Seller Integration Guide for sellers who want to sell on Facebook and Instagram while managing orders using the Commerce API.

Concepts

Seller Source of Truth: The Order Snapshot API uses the seller’s Order Management System (OMS) as the source of truth. When a seller uses the API, Meta will update the order on Meta’s system to match the seller’s, within certain constraints (see Caveats).

Snapshot model: The Order Snapshot API is snapshot-based, meaning that sellers only need to give the current state of the order in the seller’s OMS. It is not necessary to be able to provide only the iterative changes to an order (which is common for an event-based OMS, and how other Order Management APIs typically work)

Idempotent: Using the snapshot model, the Order Snapshot API is idempotent. Duplicate API requests will produce the same result as executing it once. Meta will take the most recent API call and assume that to be the Source of Truth.

Given the above concepts, the API can be integrated as a recurring update “job” if desired, though it can fit just as well into an event-based OMS if all order details are available.

Item-Level Order Snapshot

Read this section to learn how to update an order using an item-level snapshot. Refer to the Order Lifecycle documentation for the expected flow of a typical order.

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
    https://graph.facebook.com/{order-id}/item_updates

Request

Field	Type	Required	Description
`merchant_order_reference`	string	Y	Unique ID representing the order in your (seller) Order Management System. This should not change once set.
`items`	`array` of `item`	Y	Item-level representation of the order state.

`item` object

Field	Type	Required	Description
`item_id`	string	Y	Meta’s item ID.
`fulfill_quantity`	number	Y	Fulfilled quantity of the item.
`cancel_quantity`	number	Y	Canceled quantity of the item.
`refund_quantity`	number	Y	Refunded quantity of the item.
`tracking_info`	`array` of `tracking_info`	N	Array of `tracking_info` objects associated with the item, if any quantity has been fulfilled.
`fulfillment`	`fulfillment`	N	Fulfillment origin location, only if different than the default location configured for the shop. Used to properly calculate taxes.
`shipping_refund`	`shipping_refund`	N	The shipping refunded associated with the item, if any.
`deductions`	`array` of `deduction`	N	Array of `deduction` objects associated with the item, if any quantity has been refunded.
`cancel_reason`	`cancel_reason`	N	The cancellation reason and description, if any quantity has been canceled.
`refund_reason`	`refund_reason`	N	The refund reason and description, if any quantity has been refunded.

`refund_reason` object

Field	Type	Required	Description
`reason_code`	`refund_reason_code`	N	Reason code for the refund.
`reason_description`	string	N	Reason for the refund. This message may be presented to the user.

Response

Note: The Order Snapshot API supports read-after-write, which will read the latest Commerce Order Details after you POST to the API.

Field	Type	Details
`success`	boolean	If success; otherwise, error message is shown.

Examples

Order Fulfillment

Once you are ready to fulfill and ship the order, use the Order Snapshot API to ship individual order items

{
  "items": [
    {
      "item_id": "meta_item_id",
      "fulfill_quantity": 1,
      "refund_quantity": 0,
      "cancel_quantity": 0,
      "tracking_info": [
        {
          "tracking_number": "test_tracking_number",
          "carrier": "UPS"
        }
      ]
    }
  ],
  "merchant_order_reference": "seller_order_123"
}

Order Cancellation

If you need to cancel the order, use the Order Snapshot API to cancel individual order items.

{
  "items": [
    {
      "item_id": "meta_item_id",
      "fulfill_quantity": 0,
      "refund_quantity": 0,
      "cancel_quantity": 1,
      "cancel_reason": {
        "reason_code": "CUSTOMER_REQUESTED",
        "reason_description": "No longer needed"
      }
    }
  ],
  "merchant_order_reference": "seller_order_123"
}

Note: the API will return an error if you are trying to cancel items already fulfilled/refunded. You can always get the order details to review the current status of items in an order

Order Refunds

If you need to refund the order, use the Order Snapshot API to refund individual order items.

{
  "items": [
    {
      "item_id": "meta_item_id",
      "fulfill_quantity": 0,
      "refund_quantity": 1,
      "cancel_quantity": 0,
      "shipping_refund": {
        "shipping_refund": {
          "currency": "USD",
          "amount": "5.00"
        }
      }
      "refund_reason": {
        "reason_code": "BUYERS_REMORSE",
        "reason_description": "No longer needed"
      }
    }
  ],
  "merchant_order_reference": "seller_order_123"
}

Note: the API will return an error if you are trying to refund items already canceled. You can always get the order details to review the current status of items in an order

Partial Fulfillment / Cancellation / Refunds

Orders may contain one or more order line items. Order line items represent individual products that a customer has purchased in one order. As a seller, you may process each order line item independently.

The following is a sample order request with two different line items, where we operate on two line items with different operations independently. One item has been fulfilled and subsequently refunded, whereas the other item was canceled before it was fulfilled.

{
  "items": [
    {
      "item_id": "meta_item_id_1",
      "fulfill_quantity": 0,
      "refund_quantity": 2,
      "cancel_quantity": 0,
      "tracking_info": [
        {
          "tracking_number": "test_tracking_number",
          "carrier": "UPS"
        }
      ]
    },
    {
      "item_id": "meta_item_id_2",
      "fulfill_quantity": 0,
      "refund_quantity": 0,
      "cancel_quantity": 2
    }
  ],
  "merchant_order_reference": "seller_order_123"
}

Caveats

Meta will apply your order state within certain constraints and subject to typical order flow. For example, if an order is canceled but then later marked as fulfilled, Meta will be unable to apply this state as we cannot capture canceled orders. Similarly, we cannot retroactively apply changes that would result in an updated tax calculation once the order has already been captured.

For other types of updates, such as reason codes, we may not send new notifications to buyers if we’ve already notified them with the previous reason, though we may still apply the update to the order.