Returns API

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.

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”
   }],
   "return_buyer_images":[
      “<image_url_1>”,
      “<image_url_2>”
   ],
   "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

AttributeTypeDescription

id

string

Meta-generated unique return ID.

return_status

return_status

enum

Default. Status of this return.

return_message

string

Buyer-provided message when requesting a return.

merchant_return_id

string

Merchant-provided, unique return ID.

return_buyer_images

array of string

List of buyer-provided images when requesting a return.

item_return_quantities

array of item_return_quantity

List of quantities for each item in the return.

item_return_reasons

array of item_return_reason

List of reasons for each item in the return.

items

array of order_items

List of the subset of order items associated with the return.

order

order

Order for which the return was created.

return_status enum

StateDescription

APPROVED

Seller approved the return.

DISAPPROVED

Seller disapproved the return.

MERCHANT_MARKED_COMPLETED

Seller manually marked the return as completed.

REFUNDED

Seller refunded for this return request.

REQUESTED

Buyer requested a return.

reason enum

State

General return reasons

NOT_NEEDED_ANYMORE

INACCURATE_DESCRIPTION

DEFECTIVE_ITEM

BETTER_PRICE

OTHER

DAMAGED_ITEM

WRONG_ITEM_RECEIVED

BOUGHT_BY_MISTAKE

DUPLICATE_ITEM

ITEM_QUALITY_NOT_EXPECTED

Return reasons reserved for clothing, shoes and apparel

TOO_SMALL

TOO_BIG

DID_NOT_LIKE_STYLE

DID_NOT_LIKE_COLOR

ORDERED_MULTIPLE_SIZES

ORDERED_MULTIPLE_COLORS

Return reasons reserved for electronics

MISSING_PARTS

ITEM_NOT_COMPATIBLE

item_return_quantity object

AttributeTypeDescription

key

string

ID representing the item.

value

Number

Quantity of the item returned.

item_return_reason object

AttributeTypeDescription

key

string

ID representing the item.

value

Number

Reason the item was returned.

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

Attribute Type Required? Description

start_time_created

String

Optional

Fetch returns created after this date in Unix timestamp.

end_time_created

String

Optional

Fetch returns created before this date in Unix timestamp.

merchant_return_id

String

Optional

Fetch returns that have this unique merchant-provided return ID.

statuses

array of return_status enum

Optional

Return statuses to filter on.

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

Attribute Type Required? Description

merchant_return_id

String

Optional

Fetch returns that have this unique merchant-provided return ID.

statuses

array of return_status enum

Optional

Return statuses to filter on.

Response

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

Fields

Attribute Type Description

data

vec of return

Returns only default return fields. Additional data can be queried by passing in as 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

AttributeTypeDescription

items

array of item

List of returned items.

return_status

return_status

enum

Status of this return.

return_message

string

Buyer-provided message when requesting a return.

merchant_return_id

string

Merchant-provided, unique return ID.

item object

AttributeTypeDescription

item_id

string

Required if retailer_id is not provided. A Meta-generated ID representing the line item on the order. This value is readable as the id field of the item response. You must provide retailer_id or item_id, but not both. If retailer_id is provided, item_id must not be provided.

retailer_id

string

Required if item_id is not provided. ID representing the product in the seller's catalog. You must provide retailer_id or item_id, but not both. If item_id is provided, retailer_id must not be provided.

quantity

Number

Quantity of items returned.

reason

reason_enum

Reason for the return selected by the buyer.

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

AttributeTypeDescription

update_event

update_event

enum

Seller's decision on this return.

notes

string

Seller-provided notes on this return.

merchant_return_id

string

Merchant-provided, unique return id.

return_shipping_labels

array of return_shipping_label

List of seller-provided shipping labels to be used by the buyer to return items.

return_in_box_label_file_handles

array of string

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

StateDescription

ACCEPT_RETURN

Accepts this return.

CLOSE_RETURN

Closes this return.

return_shipping_label object

AttributeTypeDescription

carrier

carrier_code

enum

Reference the list of supported carrier codes.

service_name

string

Seller-provided service name from the shipping carrier; for example, Priority Mail.

tracking _number

string

Tracking number for the item.

file_handle

string

Shipping label uploaded using the instructions in Upload Labels and Using File Handles.

cost

currency_amount

Cost of the return shipping label.

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.