Returns API

Updated: Feb 7, 2025

Copy for LLM

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

Attribute	Type	Description
`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.
`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`

State	Description
`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

Attribute	Type	Description
`key`	`string`	ID representing the item.
`value`	`Number`	Quantity of the item returned.

`item_return_reason` object

Attribute	Type	Description
`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

Attribute	Type	Description
`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

Attribute	Type	Description
`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

Attribute	Type	Description
`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`

State	Description
`ACCEPT_RETURN`	Accepts this return.
`CLOSE_RETURN`	Closes this return.

`return_shipping_label` object

Attribute	Type	Description
`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.

Returns API

Query a Single Return

GET {return-id}

Summary

Request

Response

Fields

return_status enum

reason enum

item_return_quantity object

item_return_reason object

List Returns by Shop

GET {cms-id}/returns

Summary

Request

Fields

Response

List Returns by Order

GET {order-id}/returns

Summary

Request

Fields

Response

Fields

Create a Return

POST {order-id}/returns

Summary

Request

Request Params

Response

Fields

item object

Update a Return

POST {return-id}/update_return

Summary

Example: Request Params, Accept Return

Example: Request Params, Close Return

Response for all examples

Fields

update_event enum

return_shipping_label object

Upload Labels and Use File Handles

`return_status enum`

`reason enum`

`item_return_quantity` object

`item_return_reason` object

`item` object

`update_event enum`

`return_shipping_label` object