Returns API

Use this API to retrieve details for returns and to update return status.

Query a Single Return

GET {return-id}

Summary

Given a specific return ID, retrieve the current information associated with that return. Information can include the status of the return, the order it is associated with, return reason, and so on.

Request

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

Response

{
   "id":"588512618330234",
   "return_status":"REQUESTED",
   "return_message":"I am returning this because it was too small by two sizes.",
   "merchant_return_id":"RMA-12345",
   “item_return_quantities”:[{
      “key”:“28374328434347”,
      “value”:1
   }],
   “item_return_reasons”:[{
      “key”:“28374328434347”,
      “value”:“too_small”
   }],
   "order":{
      "id":”437827384982442”,
      “order_status”:{
         “state”:“COMPLETED”
      },
      “created”:"2022-05-26T18:19:22+00:00",
      “last_updated”:"2022-05-26T18:42:46+00:00"
   }
}

Fields

return_status enum

reason enum

item_return_quantity object

item_return_reason object

List Returns by Shop

GET {cms-id}/returns

Summary

Given a Commerce Merchant Settings ID representing your shop, retrieve all the possible returns associated with it. Used primarily to determine all the returns for a shop given specific filters.

Request

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

Fields

Response

{
  "data": [
    <return_1>,
    <return_2>
  ],
  "paging": {
    "cursors": {
      "before": "--sanitized_key--",
      "after": "--sanitized_key--"
    }
  }
}

List Returns by Order

GET {order-id}/returns

Summary

Given a specific order, retrieve all possible returns associated with that order.

Request

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

Fields

Response

{
  "data": [
    <return_1>,
    <return_2>
  ],
  "paging": {
    "cursors": {
      "before": "--sanitized_key--",
      "after": "--sanitized_key--"
    }
  }
}

Fields

Create a Return

POST {order-id}/returns

Summary

Given a specific order, creates a return associated with that order. The post requires information, such as the order_item ids, the reason for the returns, and the quantity of each order item. The response returns the ID of the return that was created. Only one return per order item is allowed. Optionally provide additional update information; for example, to accept the return and provide a label in the same request.

Request

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

Request Params

{
   "return_message":"I am returning this because it was too small by two sizes.",
   "merchant_return_id":"RMA-12345",
   "items":[
      {
         "item_id":"111111111",
         "quantity":1,
         "reason":"TOO_SMALL"
      }
   ],
   "update":{
      "<optionally include any of the {return-id}/update_return input below>"
   }
}

Response

{
   "id":"1234567890"
}

Fields

item object

Update a Return

POST {return-id}/update_return

Summary

Use this endpoint to update a return; for example, by accepting it and assigning a shipping label for the buyer.

Example: Request Params, Accept Return

{
  "update_event":"accept_return",
  "notes":"Make sure to bubble wrap the item when shipping it back",
  "merchant_return_id":"RMA1234567890",
  "return_shipping_labels":[
     {
        "carrier":"USPS",
        "cost":{
           "amount":"5.5",
           "currency":"USD"
        },
        "file_handle":"<file-handle>",
        "service_name":"Priority Mail",
        "tracking_number":"abc123"
     }
  ],
  "return_in_box_label_file_handles":[
     "<file-handle>",
     "..."
  ]
}

Example: Request Params, Close Return

{
   "update_event":"close_return",
   "notes":"We do not allow returns on Electronics. See our return policy.",
   "merchant_return_id":"ABC1234567890",
   "disapproval_reason":"NOT_WITHIN_MERCHANT_RETURN_POLICY"
}

Response for all examples

{
   "success":true
}

Fields

update_event enum

return_shipping_label object

Upload Labels and Use File Handles

Follow the instructions in Upload Files to upload Shipping Label files and get corresponding file handles. Use the file handles in the return_shipping_labels and return_in_box_label_file_handles parameters.