This API is currently in a beta phase. For access, please contact your Meta representative.
Use this API to retrieve details for returns and to update return status.
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.
GET https://graph.facebook.com/vX.X/{return-id} access_token: PAGE_ACCESS_TOKEN
{ "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" } }
Attribute | Type | Description |
---|---|---|
|
| Meta-generated unique return ID. |
|
enum | Default. Status of this return. |
|
| Buyer-provided message when requesting a return. |
|
| Merchant-provided, unique return ID. |
|
| List of quantities for each item in the return. |
|
| List of reasons for each item in the return. |
|
| List of the subset of order items associated with the return. |
|
| Order for which the return was created. |
return_status enum
State | Description |
---|---|
| Seller approved the return. |
| Seller disapproved the return. |
| Seller manually marked the return as completed. |
| Seller refunded for this return request. |
| Buyer requested a return. |
reason enum
State |
---|
General return reasons |
|
|
|
|
|
|
|
|
|
|
Return reasons reserved for clothing, shoes and apparel |
|
|
|
|
|
|
Return reasons reserved for electronics |
|
|
item_return_quantity
objectAttribute | Type | Description |
---|---|---|
|
| ID representing the item. |
|
| Quantity of the item returned. |
item_return_reason
objectAttribute | Type | Description |
---|---|---|
|
| ID representing the item. |
|
| Reason the item was returned. |
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.
GET https://graph.facebook.com/vX.X/{cms-id}/returns access_token: PAGE_ACCESS_TOKEN
Attribute | Type | Required? | Description |
---|---|---|---|
| String | Optional | Fetch returns created after this date in Unix timestamp. |
| String | Optional | Fetch returns created before this date in Unix timestamp. |
| String | Optional | Fetch returns that have this unique merchant-provided return ID. |
|
| Optional | Return statuses to filter on. |
{ "data": [ <return_1>, <return_2> ], "paging": { "cursors": { "before": "--sanitized_key--", "after": "--sanitized_key--" } } }
Given a specific order, retrieve all possible returns associated with that order.
GET https://graph.facebook.com/vX.X/{order-id}/returns access_token: PAGE_ACCESS_TOKEN
Attribute | Type | Required? | Description |
---|---|---|---|
| String | Optional | Fetch returns that have this unique merchant-provided return ID. |
|
| Optional | Return statuses to filter on. |
{ "data": [ <return_1>, <return_2> ], "paging": { "cursors": { "before": "--sanitized_key--", "after": "--sanitized_key--" } } }
Attribute | Type | Description |
---|---|---|
|
| Returns only default return fields. Additional data can be queried by passing in as fields. |
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.
POST https://graph.facebook.com/vX.X/{order-id}/returns access_token: PAGE_ACCESS_TOKEN
{ "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>" } }
{ "id":"1234567890" }
Attribute | Type | Description |
---|---|---|
|
| List of returned items. |
|
enum | Status of this return. |
|
| Buyer-provided message when requesting a return. |
|
| Merchant-provided, unique return ID. |
item
objectAttribute | Type | Description |
---|---|---|
|
| Required if |
|
| Required if |
|
| Quantity of items returned. |
|
| Reason for the return selected by the buyer. |
Use this endpoint to update a return; for example, by accepting it and assigning a shipping label for the buyer.
{ "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>", "..." ] }
{ "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" }
{ "success":true }
Attribute | Type | Description |
---|---|---|
|
enum | Seller's decision on this return. |
|
| Seller-provided notes on this return. |
|
| Merchant-provided, unique return id. |
|
| List of seller-provided shipping labels to be used by the buyer to return items. |
|
| List of labels uploaded using the instructions in Upload Labels and Using File Handles. Use it if you need to instruct the buyer to include labels inside the returned box. |
update_event enum
State | Description |
---|---|
| Accepts this return. |
| Closes this return. |
return_shipping_label
objectAttribute | Type | Description |
---|---|---|
|
enum | Reference the list of supported carrier codes. |
|
| Seller-provided service name from the shipping carrier; for example, Priority Mail. |
|
| Tracking number for the item. |
|
| Shipping label uploaded using the instructions in Upload Labels and Using File Handles. |
| Cost of the return shipping label. |
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.