Return Data Integration (API)

This endpoint allows partners to send one or multiple product return records to Sizebay.

⚠ 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.

Try it out: Open in Swagger UI

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

POST 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

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

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

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

{
  "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., “very long sleeve”);

• Notes for internal tracking or analytics.