Order Snapshot API

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

item object

refund_reason object

Response

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

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

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.

Learn More

• Cancellation and Refund API
• Fulfillment API Reference