Table of Contents
Variables
merchantAPIEndpoint:https://merchant.api.shopflix.gr/v2orderId:GR--3001--MER78returnId:GR--3--MER78-R1
Returns
1. Get Returns
GET {{merchantAPIEndpoint}}/returnsParameters
| Name | Type | Description | Required | Default | Example |
|---|---|---|---|---|---|
state | string | Filter by return state (e.g., return-registered) | No | null | return-registered |
dateFrom | date | Filter orders from this date (ISO 8601) | No | null | 2023-12-01 |
dateTo | date | Filter orders to this date (ISO 8601) | No | null | 2023-12-01 |
page | number | Starting page for pagination. | No | 1 | 1 |
itemsPerPage | number | Items per page. | No | 10 | 10 |
Return States
| State | Description |
|---|---|
return-registered | The return has been created and is pending voucher creation. |
return-voucher-created | A return shipping label (voucher) has been generated. |
delivering-to-store | The package is currently in transit to the merchant. |
delivered-to-store | The return has been delivered to the merchant’s location. |
waiting-for-support-approval | Awaiting manual approval by customer support. |
return-completed | The return has been successfully processed and completed. |
return-canceled | The return has been canceled by the customer or system. |
Example
GET {{merchantAPIEndpoint}}/returns?page=1&itemsPerPage=10Response
✅ Status: 200 OK
Content-Type: application/json
{
"params": {
"page": 1, // Current page number
"itemsPerPage": 10, // Number of items returned per page
"totalItems": 2, // Total number of available returns
"status": null, // Return status filter (null = no filter applied)
"dateFrom": null, // Start date filter for returns (null = no limit)
"dateTo": null // End date filter for returns (null = no limit)
},
"returns": [
{
"id": "GR--3292--MER78-R4", // Return reference ID
"orderId": "GR--3292--MER78", // Original order reference
"state": "return-canceled", // Current return state
"countryCode": "GR", // Country code
"totalItemsAmount": 100, // Total amount of returned items
"createdAt": "2025-10-06 17:01:45", // Return creation timestamp
"updatedAt": "2025-10-06 17:01:45", // Last update timestamp
"customer": {
"userId": null, // Internal customer identifier (null = guest)
"email": "sarah@example.com", // Customer email address
"phone": "425-222-45-76", // Customer phone number
"firstName": "Sarah", // Customer first name
"lastName": "Muller" // Customer last name
}
},
{
"id": "GR--3256--MER78-R153", // Return reference ID
"orderId": "GR--3256--MER78", // Original order reference
"state": "delivered-to-store", // Return state (delivered back to store)
"countryCode": "GR", // Country code
"totalItemsAmount": 2146, // Total amount of returned items
"createdAt": "2025-09-05 13:51:17", // Return creation timestamp
"updatedAt": "2025-09-05 13:51:17", // Last update timestamp
"customer": {
"userId": null, // Internal customer identifier
"email": "maria.williams@example.com", // Customer email
"phone": "", // Customer phone number (empty if not provided)
"firstName": "Maria", // Customer first name
"lastName": "Williams" // Customer last name
}
}
// More return entries can be listed here...
]
}Example with status
GET {{merchantAPIEndpoint}}/returns?page=1&itemsPerPage=10{
"params": {
"page": 1,
"itemsPerPage": 10,
"totalItems": 2,
"status": "return-voucher-created",
"dateFrom": null,
"dateTo": null
},
"returns": [
{
"id": "GR--3--MER78-R1",
"orderId": "GR--3--MER78",
"state": "return-voucher-created",
"countryCode": "GR",
"totalItemsAmount": 100,
"createdAt": "2025-10-06 17:01:45",
"updatedAt": "2025-10-06 17:01:45",
"customer": {
"userId": null,
"email": "Sarah@spryker.com",
"phone": "425-222-45-76",
"firstName": "Muller",
"lastName": "Muller"
}
}
...
]
}
2. Retrieve single return
GET {{merchantAPIEndpoint}}/returns/{returnId}Response
✅ Status: 200 OK
Content-Type: application/json
{
"id": "GR--3292--MER78-R4", // Return reference ID
"orderId": "GR--3292--MER78", // Reference of the original order
"state": "return-canceled", // Current return state
"countryCode": "GR", // Country code
"totalItemsAmount": 100, // Total amount of returned items
"createdAt": "2025-10-06 17:01:45", // Return creation timestamp
"updatedAt": "2025-10-06 17:01:45", // Last update timestamp
"customer": {
"userId": null, // Internal customer identifier (null = guest)
"email": "sarah@example.com", // Customer email address
"phone": "425-222-45-76", // Customer phone number
"firstName": "Sarah", // Customer first name
"lastName": "Muller" // Customer last name
},
"addressDetails": null, // Return address details (null if not applicable)
"carrier": null, // Carrier information (null if not assigned)
"lineItems": [
{
"id": 308, // Return line item identifier
"sku": "SF-2", // Product SKU
"merchantEan": "sf-foo-bar-6", // Merchant EAN
"merchantSku": "MERSKU6", // Merchant SKU
"productName": "Phone", // Product name
"unitPrice": 100, // Unit price
"originalUnitPrice": null, // Original unit price (null if not applicable)
"totalPrice": 100, // Total price for this line item
"quantity": 1, // Quantity returned
"sfArticle39Valid": null, // Business rule flag (null if not evaluated)
"giftWrap": null, // Gift wrap flag (null if not applicable)
"extendedAttributes": [] // Additional attributes (can be empty)
}
// Additional returned items may follow...
]
}3. Accept Return
POST {{merchantAPIEndpoint}}/returns/{returnId}/acceptResponse
✅ Status: 200 OK
Content-Type: application/json
❌ Error Response
{
"error": {
"code": "10312",
"message": "Cannot Accept Return"
}
}Possible reasons
- This might happen if the return has already been processed, canceled, or completed.
4. Reject Return
POST {{merchantAPIEndpoint}}/returns/{returnId}/reject`Response
✅ Status: 200 OK
Content-Type: application/json
❌ Error Response
{
"error": {
"code": "10312",
"message": "Cannot Accept Reject"
}
}Error Codes
| Code | Message | Explanation |
|---|---|---|
10312 | Cannot Accept Return | The return cannot be accepted due to an invalid state. |
10313 | Cannot Reject Return | The return cannot be rejected due to an invalid state. |
10301 | The return with id was not found | The provided returnId does not exist or is invalid. |
10401 | The return cannot be processed. | The return is in an invalid state for this action. |
Quick Reference
| Endpoint | Description | Method | Response |
|---|---|---|---|
/returns | List all returns (with filters) | GET | Paginated list |
/returns/{returnId} | Retrieve a specific return | GET | Return details |
/returns/{returnId}/accept | Accept the return | POST | success: true |
/returns/{returnId}/reject | Reject the return | POST | success: true |