Returns API

Create a Return

To create a new return, you need to check the Query Orders API endpoint, when querying a single product (by providing filter.id=...), it will return a returnableProducts array.

You need to display in your UI the following key elements:

• Quantity to be returned (min 0, max returnableProducts[n].returnableQuantity)
• Reason for the return (see returnableProducts[n].returnableReasons)
• A generic "More information" textarea.

A typical return form

POST /returns

{
    "orderId": "9f74936e-f91e-4cf9-a4de-7efc3b263604",
    "idempotencyKey": "any-key-you-want",
    "productId": "a42ff15d-858f-4166-86bc-0f969dec67b9",
    "quantity": 2,
    "reasonCode": "changed_mind",
    "address": {
        "id": "ed8b291c-d7e6-4d5c-82cb-0febbe9218cc"
        // ... or a full Address Object
    }
}

Response (200)

{
    "id": "38b71898-b835-4dc5-b578-3df5c19d0bac"
}

Query Returns

GET /returns

Property	Description	Example
filter.userId	Returns only returns created by this user.	?filter.userId=any-unique-id-from-your-system
filter.idempotencyKey	Filters by idempotency key.	&filter.idempotencyKey=$in:key1,key2
filter.status	Filters by the status of the return. See Returns Lifecycle.	&filter.status=$in:success,pending
filter.id	Filter by return ID, useful if you want to display the return page for a specific order.	&filter.id=9f74936e-f91e-4cf9-a4de-7efc3b263604
filter.amount	Filters by order amount	&filter.amount=$gt:10000

Response (200

{
    "returns": [
        {
            "id": "38b71898-b835-4dc5-b578-3df5c19d0bac",
            "orderId": "9f74936e-f91e-4cf9-a4de-7efc3b263604",
            "idempotencyKey": "any-key-you-want",
            "productId": "a42ff15d-858f-4166-86bc-0f969dec67b9",
            "status": "canceled.pickup-failed",
            "reasonCode": "changed_mind",
            "quantity": 2,
            "address":  {
                "id": "ed8b291c-d7e6-4d5c-82cb-0febbe9218cc",
                "phone": "+201012720555",
                "additionalPhone": "+201012720555",
                "address": "Street 23, Building 6B, Maadi",
                "additionalInfo": "6th Floor, left after elevator",
                "region": "Al Beheira",
                "city": "Maadi-Maadi Degla",
            },
            "quantity": 2,
            "amount": 172000,
            "currency": "EGP",
            "product": {
                // a Product Object
            }
        }
    ], 
    "pagination": {
        "totalItems": 12,
        "currentPage": 1,
        "pageSize": 25,
        "totalPages": 1
    },
}

Status Updates

You will receive status updates for returns through the Webhook.