Integration Guide

Use this guide to successfully integrate to the Commerce API platform. As a developer or technical manager, you will learn how to:

  • Create a catalog that powers your checkout-enabled shop
  • Create an order
  • How to manage the order from the initial purchase to a cancellation or refund

You can perform all requests from your browser via our Graph API Explorer tool.

Before You Begin

To successfully integrate to the Commerce API, you need to do the following:

  1. Onboard to the Sandbox Commerce Account.
  2. Create an application.
  3. Generate a page access token.
  4. Connect your app to Commerce Manager.
  5. Add a product to a catalog and create a test order.

Learn the Variables

This guide uses VARIABLE syntax to highlight values that need to be replaced by real values before you execute certain actions.

Variables used in this guide:

  • PAGE_ID - The id of your test page. Is obtained from the me endpoint using page access token
  • API_VERSION - Use the latest API version
  • ACCESS_TOKEN - Access token obtained
  • ORDER_ID - Order identifier obtained from the Get Orders endpoint
  • UUID - Single use, Online UUID Generator tool

Prepare New Orders

To prepare all new orders to be processed by your order management system, use the commerce_orders API endpoint. Learn more about order state.

Request — Graph API Explorer

curl -X GET -G \
  -d 'state=CREATED' \
  -d 'fields=id,buyer_details,channel,merchant_order_id,order_status' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/commerce_orders

Response

{
  "data": [
    {
      "id": "3565497390177110",
      "buyer_details": {
        "name": "John Doe",
        "email": "7dvra5wfy2@commerce.facebook.com",
        "email_remarketing_option": false
      },
      "channel": "facebook",
      "order_status": {
        "state": "CREATED"
      }
    }
  ],
  "paging": {
    "cursors": {
      "before": "--SANITIZED--",
      "after": "--SANITIZED--"
    }
  }
}

Considerations

  • The response contains the ORDER_ID variable in the data[].id field, which will be used in subsequent requests to identify the operation on this specific order.
  • The data[].buyer_details.email field contains a proxy email address for the customer if data[].buyer_details.email_remarketing_option is false; otherwise, it’s real customer email address.
  • The data[].channel field represents the source of this order; that is, facebook or instagram.
  • There might be more new orders present in the response. Use pagination cursors to ensure you consumed all new orders.
  • To see all possible fields, see the Order API Reference.

If your response has empty data, make sure that you’re using a page access token, not a user access token.

Acknowledge an Order

After an order is successfully stored in your Order Management System, you need to acknowledge that you are in a process of fulfilling a given order. To do that, use the Acknowledgement API. To acknowledge a created order, take {{ORDER_ID}} from the previous data[].id response field and call the Acknowledgement API.

Request - Graph API Explorer

curl -X POST \
  -F '{
    "idempotency_key": "<UUID>"
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/<ORDER_ID>/acknowledge_order

Response

{
  "id": "3565497390177110",
  "state": "IN_PROGRESS"
}

Considerations

Check Order Status

The order status is a helpful endpoint to check if order is in expected state or to get additional fields. In this example, make sure that the order is in the "IN_PROGRESS" state after the previous acknowledgement request.

Request - Graph API Explorer

curl -X GET -G \
  -d 'fields=id,order_status' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/<ORDER_ID>

Response

{
  "id": "3565497390177110",
  "order_status": {
    "state": "IN_PROGRESS"
  }
}

Considerations

  • The order state is now nested in the order_status field, which differs from the acknowledgement response.
  • We’re receiving only fields we requested.
  • See the list of all fields.

Ship an Order

To attach a shipment to an order after it was shipped to a customer, take ORDER_ID from the order API response and call the Shipments, Commerce API endpoint.

Request - Graph API Explorer

curl -X POST \
  -F '{
    "external_shipment_id": "shipment_1",
    "items": [
      {
        "retailer_id": "FB_T_Shirt_001",
        "quantity": 1
      }
    ],
    "tracking_info": {
      "tracking_number": "1Z204E380338943508",
      "carrier": "UPS",
    },
    "idempotency_key": "<UUID>"
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/<ORDER_ID>/shipments

Response

{
   "success": true
}

Considerations

  • Set the external_shipment_id request field to any (alphanumeric and “_”) identifier you choose to later reference this shipment
  • The items request field that contains an array of objects with retailer_id and quantity representing which products and how many are part of this shipment.
  • The tracking_info request field represents the object with tracking information where carrier is one of the supported carriers, and tracking_number is a tracking code.
  • The customer is charged at the moment a shipment is attached to an order.
  • See the list of all supported request fields.

Retrieve List of Shipment Orders

Use the order Shipments endpoint to retrieve a list of all shipments attached to an order and to get additional fields. In this case, we recommend to ensure sure that your shipment is attached to the order.

Request - Graph API Explorer

curl -X GET -G \
  -d 'fields=id,shipping,tracking_info,items' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/<ORDER_ID>/shipments

Response

{
   "data": [
       {
           "id": "476186406358667",
           "items": {
               "data": [
                   {
                       "id": "475451323098842",
                       "product_id": "2656746411045789",
                       "retailer_id": "FB_T_Shirt_001",
                       "quantity": 1,
                       "tax": {
                           "final_tax": {
                               "amount": "0.09",
                               "currency": "USD"
                           }
                       }
                   }
               ]
           },
           "tracking_info": {
               "tracking_number": "1Z204E380338943508",
               "carrier": "ups"
           }
       }
   ],
   "paging": {
       "cursors": {
           "before": "--SANITIZED--",
           "after": "--SANITIZED--"
       }
   }
}

Considerations

  • The response contains a list of all shipments attached to one or more orders.
  • Each shipment contains separate unique tracking information.
  • The items response field contains information about every product that was part of this shipment and final tax (might differ from the estimated_tax field in order detail endpoint.
  • See the list of available fields.

Refund an Order

To refund an order that was already shipped, take the order ID from the order API response and call the refund API.

Request - Graph API Explorer

curl -X POST \
  -F '{
   "reason_code": "WRONG_ITEM",
   "idempotency_key": "<UUID>"
}' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/<ORDER_ID>/refunds

Response

{
   "success": true
}

Considerations

For a list of possible refund reasons, see refund_reason_code enum.

Retrieve Order Refunds

Order refunds is a helpful endpoint to retrieve a list of all refunds in an order and to get any additional fields. In this case, we recommend to ensure that your refund is attached to the order.

Request - Graph API Explorer

curl -X GET -G \
  -d 'fields=id,refund_amount,refund_reason,items' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/<ORDER_ID>/refunds

Response

{
   "data": [
       {
           "id": "481968142447160",
           "items": {
               "data": [
                   {
                       "id": "475451323098842",
                       "product_id": "2656746411045789",
                       "retailer_id": "FB_T_Shirt_001"
                   }
               ]
           },
           "refund_amount": {
               "amount": "1.09",
               "currency": "USD"
           }
       }
   ],
   "paging": {
       "cursors": {
           "before": "--SANITIZED--",
           "after": "--SANITIZED--"
       }
   }
}

Considerations

  • The response contains a list of all refunds attached to one or more orders.
  • The items response field contains information about every product that was part of the specified refund.

Cancel Orders

To cancel an order that wasn’t shipped yet, take ORDER_ID from the order API response and call the cancel order API.

Request - Graph API Explorer

curl -X POST \
  -F '{
 "cancel_reason": {
   "reason_code": "CUSTOMER_REQUESTED",
   "reason_description": "Buyer did not need it anymore"
 },
 "restock_items": true,
 "items": [
   {
     "retailer_id": "FB_T_Shirt_001",
     "quantity": 1
   }
 ],
 "idempotency_key": "<UUID>"
}' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/<ORDER_ID>/cancellations

Response

{
   "success": true
}

Considerations

For a list of possible refund reasons, see refund_reason_code enum.

Retrieve Order Cancellations

Use the order cancellation endpoint to retrieve a list of all cancellations in order and to get any additional fields. In the following example, the cancellation is attached to the order.

Request - Graph API Explorer

curl -X GET -G \
  -d 'fields=cancel_reason,id,items' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/<ORDER_ID>/refunds

Response

{
  "data": [
    {
      "id": "3565497390177110",
      "items": {
        "data": [
          {
            "id": "980280749116508",
            "product_id": "3528003297246976",
            "retailer_id": "FB_T_Shirt_001",
            "quantity": 1
          }
        ]
      },
      "cancel_reason": {
        "reason_code": "CUSTOMER_REQUESTED",
        "reason_description": "Buyer did not need it anymore"
      }
    }
  ],
  "paging": {
    "cursors": {
      "before": "--SANITIZED--",
      "after": "--SANITIZED--"
    }
  }
}

Considerations

  • The response contains a list of all cancellations attached to one or more orders.
  • The items response field contains information about every product that was part of the specific cancellation.

You have successfully completed the order management life cycle from your first order acknowledgement — all the way to refunds and cancellations. You should now have a good understanding of the Commerce Platform API. To learn more about how to manage your integration's performance, see our Best Practices.

FAQ

Q: Can I do Transaction API requests in my Sandbox account?

A: No, unfortunately transactions API is not available in a Sandbox account.

Q:Can I utilize product launches in my Sandbox account?

A: No, unfortunately product launches are not available in a Sandbox account.