> For the complete documentation index, see [llms.txt](https://docs.sizebay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sizebay.com/size-and-fit-data-integration/return-data-integration-api.md).

# Return Data Integration (API)

{% hint style="info" %}
**Try it out:** Open in [Swagger UI](https://returns.internalsizebay.com/api/docs#/)
{% endhint %}

### **Create Return Items**

Creates **one or more return items** in the system.\
Returns status `201 Created` with a `results` array containing the processing outcome for each item.

### **Authentication**

Each request must include the following header:

| Header      | Type     | Required | Description                             |
| ----------- | -------- | -------- | --------------------------------------- |
| `x-api-key` | `string` | ✅        | Authentication key provided by Sizebay. |

#### **Endpoint**

<mark style="color:green;">`POST`</mark> `https://returns.internalsizebay.com/returns`

#### **Request Body**

The request body must be sent as **JSON**, containing one or more return items in the `returns` array.

**Example Request**

```scheme
{
  "returns": [
    {
      "orderId": "ORD-12345",
      "orderDate": "28/08/2025",
      "productIdentifier": "396575_194",
      "sizeOrdered": "M",
      "quantity": 1,
      "returnReason": "BIG",
      "returnDate": "10/10/2025",
      "comment": "very long sleeve"
    }
  ],
  "processType": "PRODUCT_ID",
  "ignoreOrderedSize": false,
  "domain": "www.example.com"
}
```

**Request Body Fields**

**ReturnItemDto**

Represents an individual return item.

<table><thead><tr><th width="174.3984375">Field</th><th width="114.32421875">Type</th><th width="115.93359375">Required</th><th>Example</th><th>Description</th></tr></thead><tbody><tr><td><code>orderId</code></td><td><code>string</code></td><td>✅</td><td><code>ORD-12345</code></td><td>The original order ID.</td></tr><tr><td><code>orderDate</code></td><td><code>string</code></td><td>✅</td><td><code>28/08/2025</code></td><td>Order date in <code>DD/MM/YYYY</code> format.</td></tr><tr><td><code>productIdentifier</code></td><td><code>string</code></td><td>✅</td><td><code>396575_194</code></td><td>Product identifier (SKU, Product ID, or Permalink depending on <code>processType</code>).</td></tr><tr><td><code>sizeOrdered</code></td><td><code>string</code></td><td>✅</td><td><code>M</code></td><td>The size purchased.</td></tr><tr><td><code>quantity</code></td><td><code>number</code></td><td>✅</td><td><code>1</code></td><td>Quantity being returned. Minimum value: <code>1</code>.</td></tr><tr><td><code>returnReason</code></td><td><code>string</code></td><td>✅</td><td><code>BIG</code></td><td>Reason for the return.Accepted values: <code>UNKNOWN</code>, <code>SMALL</code>, <code>BIG</code>.</td></tr><tr><td><code>returnDate</code></td><td><code>string</code></td><td>❌</td><td><code>10/10/2025</code></td><td>Return date in <code>DD/MM/YYYY</code> format. Defaults to today’s date if not provided.</td></tr><tr><td><code>comment</code></td><td><code>string</code></td><td>❌</td><td><code>"Customer mentioned item was too large"</code></td><td>Optional field for any additional notes, such as customer feedback, RMA numbers, or internal remarks for intelligence analysis.</td></tr></tbody></table>

**ReturnsDto**

Represents the main object containing all return data.

| Field               | Type      | Required | Example                | Description                                                                            |
| ------------------- | --------- | -------- | ---------------------- | -------------------------------------------------------------------------------------- |
| `returns`           | `array`   | ✅        | `[ReturnItemDto, ...]` | List of one or more return items.                                                      |
| `processType`       | `string`  | ✅        | `PRODUCT_ID`           | Defines the product matching logic. Accepted values: `PRODUCT_ID`, `SKU`, `PERMALINK`. |
| `ignoreOrderedSize` | `boolean` | ❌        | `false`                | Whether to ignore the ordered size when matching.                                      |
| `domain`            | `string`  | ✅        | `www.example.com`      | The domain of the store associated with this return batch.                             |

#### **Response**

Returns a summary of the operation results for each return item.

**Example Response**

```scheme
{
  "results": [
    {
      "index": 0,
      "status": "created"
    }
  ]
}
```

**BatchReturnResponseDto**

| Field     | Type    | Required | Description                                     |
| --------- | ------- | -------- | ----------------------------------------------- |
| `results` | `array` | ✅        | List of results for each processed return item. |

**ReturnItemResponseDto**

| Field     | Type     | Required | Example                           | Description                                  |
| --------- | -------- | -------- | --------------------------------- | -------------------------------------------- |
| `index`   | `number` | ✅        | `0`                               | Index of the item in the submitted batch.    |
| `status`  | `string` | ✅        | `created`                         | Operation result (`created`, `error`, etc.). |
| `code`    | `string` | ❌        | `INVALID_QUANTITY`                | Error code, if applicable.                   |
| `message` | `string` | ❌        | `quantity must be greater than 0` | Error message, if applicable.                |

#### **Response Codes**

| Code                        | Description                             |
| --------------------------- | --------------------------------------- |
| `201 Created`               | Return items created successfully.      |
| `400 Bad Request`           | Validation error in the submitted data. |
| `401 Unauthorized`          | Missing or invalid API key.             |
| `500 Internal Server Error` | Unexpected server error.                |

#### **Tip**

Use the `"comment"` field to include **contextual information** about the return, such as:

* Customer feedback (e.g., *“*&#x76;ery long sleev&#x65;*”*);
* Notes for internal tracking or analytics.