# Return Data Integration (API)

> ⚠ **Beta Notice**\
> This API endpoint is currently in **beta**. It may change or behave differently in future versions. Use it with caution and report any issues to our team.

{% 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sizebay.com/size-and-fit-data-integration/return-data-integration-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.