Create Return

POST

/partner/v1/returns

Records a POS return and submits it for review. The order is recorded from products, so send every line of the original sale; lines with return_quantity > 0 are the ones returned.

Money is in minor units (halalas): 10000 = 100.00 SAR. discount and tax are for the whole line.

Idempotent on external_return_id per store when sent: re-sending the same external_return_id returns the existing return instead of creating a duplicate — safe to retry on timeouts.

bank_transfer needs iban + account_holder_name; the IBAN is validated and saved to the customer.

Scope: refunds:write.

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Header Params

Body Params application/jsonRequired

Examples

Responses

🟢201Created

application/json

Bodyapplication/json

🟠400Validation failed

🟠409Conflict

🟠422Not eligible

🟠401Unauthorized

🟠403Forbidden

🟠429Too Many Requests

Request Example

Shell

JavaScript

Java

Swift

curl --location '/partner/v1/returns' \
--header 'X-Store-Id: {{partner_store_id}}' \
--header 'Accept-Language: en' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "external_return_id": "{{partner_external_return_id}}",
    "order": {
        "id": "{{partner_external_order_id}}",
        "number": "INV-88231",
        "purchased_at": "{{partner_purchased_at}}",
        "currency": "SAR",
        "payment_method": "mada"
    },
    "customer": {
        "id": "CUST-501",
        "name": "Sara Al-Qahtani",
        "phone": "+966501234567",
        "email": "sara@example.com"
    },
    "products": [
        {
            "line_id": "L-1",
            "product_id": "P-100",
            "variant_id": "V-100-M",
            "sku": "TSH-BLK-M",
            "name": "Classic Cotton T-Shirt",
            "quantity": 3,
            "unit_price": 10000,
            "discount": 0,
            "tax": 4500,
            "return_quantity": 2,
            "reason_id": "{{partner_reason_id}}",
            "note": "Wrong size"
        },
        {
            "line_id": "L-2",
            "product_id": "P-200",
            "sku": "CAP-NVY",
            "name": "Baseball Cap",
            "quantity": 1,
            "unit_price": 5000,
            "discount": 500,
            "tax": 675,
            "return_quantity": 0
        }
    ],
    "resolution": {
        "method": "bank_transfer",
        "iban": "SA0380000000608010167519",
        "account_holder_name": "Sara Al-Qahtani"
    }
}'

Response Example

201 - Example 1

{
    "success": true,
    "message": "string",
    "data": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "external_return_id": "string",
        "request_number": 0,
        "status": "string",
        "refund_status": "string",
        "source": "string",
        "return_reason": "string",
        "order_id": "string",
        "currency": "string",
        "requested_amount": 0,
        "final_amount": 0,
        "items": [
            {
                "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
                "line_id": "string",
                "name": "string",
                "sku": "string",
                "unit_price": 0,
                "tax": 0,
                "discount": 0,
                "reason": {
                    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
                    "name": {
                        "en": "string",
                        "ar": "string"
                    },
                    "return_types": [
                        "string"
                    ]
                },
                "status": "string"
            }
        ],
        "refunds": [
            {
                "method": "string",
                "amount": 0,
                "status": "string",
                "payment": {
                    "transaction_reference": "string",
                    "status": "string",
                    "amount": 0,
                    "fee": 0,
                    "currency": "string",
                    "value_date": "2019-08-24",
                    "from": {
                        "name": "string",
                        "account": "string",
                        "bic": "string"
                    },
                    "to": {
                        "name": "string",
                        "account": "string",
                        "bic": "string"
                    },
                    "created_at": "2019-08-24T14:15:22.123Z"
                }
            }
        ],
        "attachments": [
            {
                "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
                "url": "string",
                "media_type": "string",
                "created_at": "2019-08-24T14:15:22.123Z"
            }
        ],
        "shipments": [
            {
                "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
                "direction": "string",
                "status": "string",
                "tracking_number": "string",
                "carrier_tracking_number": "string",
                "tracking_url": "string",
                "label_url": "string",
                "created_at": "2019-08-24T14:15:22.123Z"
            }
        ],
        "invoice_url": "string",
        "submitted_at": "2019-08-24T14:15:22.123Z",
        "approved_at": "2019-08-24T14:15:22.123Z",
        "rejected_at": "2019-08-24T14:15:22.123Z",
        "completed_at": "2019-08-24T14:15:22.123Z",
        "created_at": "2019-08-24T14:15:22.123Z"
    }
}

Upload Return Attachment

List Returns