# Returns API



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

## Query a Single Return

### GET {return-id} {#query}

### 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`<br><br>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 {#returnsbyshop}

### 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

```curl
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

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

## List Returns by Order {#returnsbyorder}

### GET {order-id}/returns

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

### Request

```curl
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

```json
{
  "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 {#create}

### 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`<br><br>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.<br>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.<br>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 {#update}

### 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`<br><br>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](#upload-labels). 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`<br><br>enum | Reference the [list of supported carrier codes](https://developers.facebook.com/documentation/ads-commerce/commerce-platform/order-management/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](#upload-labels). |
| `cost` | [`currency_amount`](https://developers.facebook.com/documentation/ads-commerce/commerce-platform/order-management/cancellation-refund-api#currency_amount) | Cost of the return shipping label. |

### Upload Labels and Use File Handles {#upload-labels}

Follow the instructions in [Upload Files](https://developers.facebook.com/docs/graph-api/guides/upload) 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.