Returns

Table of Contents 📖

Variables

merchantAPIEndpoint: /api
orderId: GR--3001--MER78
returnId: GR--3--MER78-R1

1. Get Returns

example

GET {merchantAPIEndpoint}/returns

Parameters

Parameter	Description
status	Select returns by status (e.g., `https://merchant.api.shopflix.gr/api/returns?status=V`)
date_from	Select returns by date (e.g., `api/returns?date_from=2022-01-01`)
date_to	Select returns by date range (e.g., `api/returns?date_from=2022-01-01&date_to=2022-01-05`)

Return Status Mapping:

Status Code	Status	Mapped OMS State
'U'	Return requested	return-registered
'A'	On the way to the store	delivering-to-store
'T'	Delivered to the store	delivered-to-store
'V'	Return completed	return-completed
'W'	Processing return	waiting-for-support-approval
'X'	Return declined	return-canceled

Example

GET {merchantAPIEndpoint}/returns?page=1&itemsPerPage=10

Response

✅ Status: 200 OK

Content-Type: application/json

{
    "params": {
        "page": 1,  // Current page number of the results
        "items_per_page": 10,  // Number of items displayed per page
        "total_items": 2,  // Total number of returned orders
        "status": null,  // Filter by order status (null means no filter applied)
        "date_from": null,  // Start date filter for return orders
        "date_to": null  // End date filter for return orders
    },
    "orders": [
        {
            "return_order_id": 3256,  // The order ID in shopflix.gr
            "return_order_reference": "GR--3256--MER78-R153",  // Reference code for the return
            "order_id": 3256,  // Order registration date (Unix timestamp)
            "order_reference": "GR--3256--MER78",  // Reference code for the order
            "timestamp": 1757080277,  // Order registration date (Unix timestamp)
            "firstname": "Williams",   // Customer's first name
            "lastname": "Williams",  // Customer's last name
            "email": "maria.williams@spryker.com",  // Customer's email address
            "phone": "",  // Customer's phone number
            "status": "T",  // Order status (G = In processing)
            "total": "21.46"  // Total order cost
        },
 
        // More orders can be listed here...
    ]
}

2. Retrieve single return

GET {merchantAPIEndpoint}/returns/{returnId}

Response

✅ Status: 200 OK

Content-Type: application/json

{
    "return_order_id": 3004,  // The ID of the returned order in shopflix.gr
    "return_order_reference": "GR--3004--MER78-R1",  // The reference code for the returned order
    "order_id": 3004,  // The ID of the original order in shopflix.gr
    "order_reference": "GR--3004--MER78",  // The reference code of the original order
    "status": "A",  // The status of the return order
    "timestamp": 1738329930,  // UNIX timestamp of when the return order was created
    "total": "23.46",  // Total refund amount (including shipping)
    "subtotal": "23.46",  // Subtotal of returned products (excluding shipping)
    "company_id": "",  // The ID of the associated vendor (empty if not applicable)
    "notes": null,  // Any notes related to the return order
    "firstname": "Muller",  // Customer's first name
    "lastname": "Muller",  // Customer's last name
    "b_firstname": "Muller",  // Customer's first name (billing)
    "b_lastname": "Muller",  // Customer's last name (billing)
    "b_address": null,  // Billing address
    "b_address2": null,  // Billing address (line 2)
    "b_city": null,  // Billing city
    "b_state": null,  // Billing state
    "b_country": null,  // Billing country
    "b_zipcode": null,  // Billing postal code
    "b_phone": "",  // Billing phone number
    "s_firstname": "Muller",  // Customer's first name (shipping)
    "s_lastname": "Muller",  // Customer's last name (shipping)
    "s_address": null,  // Shipping address
    "s_address2": null,  // Shipping address (line 2)
    "s_city": null,  // Shipping city
    "s_state": null,  // Shipping state
    "s_country": null,  // Shipping country
    "s_zipcode": null,  // Shipping postal code
    "s_phone": "",  // Shipping phone number
    "s_address_type": "",  // Type of shipping address
    "phone": "425-222-45-76",  // Customer's phone number
    "email": "Sarah@example.com",  // Customer's email address
    "fields": [],  // Additional custom fields for the order
    "b_country_descr": "",  // Billing country description
    "s_country_descr": "",  // Shipping country description
    "b_state_descr": "",  // Billing state description
    "s_state_descr": "",  // Shipping state description
    "shipment_ids": [],  // IDs of associated shipments
    "company_name": null,  // Name of the associated vendor (if applicable)
    "last_order_change": "",  // Last modification timestamp of the order
    "products": {
        "308": {
            "item_id": "SF-2",  // Unique ID of the returned product
            "order_id": 3004,  // The original order ID linked to this product
            "product_id": "SF-2",  // The product ID in shopflix.gr
            "product_code": "SF-2",  // The product code in the vendor's system
            "price": 23.46,  // Price of the returned product
            "amount": 1,  // Quantity of returned product
            "product": "Phone",  // Name of the product
            "product_status": "A",  // Status of the product
            "master_product_code": "SF-2",  // Master product code
            "company_id": "",  // ID of the associated vendor (if applicable)
            "base_price": "23.46",  // Base price of the product
            "original_price": "23.46",  // Original price before discounts
            "ean": "SF-2"  // European Article Number (EAN) of the product
        }
    }
}

❌ Status: 400 BAD REQUEST

Error Response if Return Not Found

response

{
    "message": "The return with id {returnId} was not found"
}

3. Accept/Reject Return

PUT {merchantAPIEndpoint}/returns/{returnId}

Request Body

Content-Type: application/json

{
    "status":"W"
}

Status codes

V = Accept
W = Reject

Response

✅ Status: 200 OK

Content-Type: application/json

response

{
	"message": "success"
}

❌ Status: 400 BAD REQUEST

The return request could not be processed because the order is in a state that does not allow accept.

response

{
    "message": "Cannot Accept Return"
}

The return cannot be rejected because it is in a state that does not allow rejection.

response

{
    "message": "Cannot Reject Return"
}

Possible reasons

This might happen if the return has already been processed, canceled, or completed.

Shipments Orders