Create Exchange Orders

Request

Method: POST
Endpoint: /orders/exchange
Content-Type: application/json

Request Body

Field Name	Required	Type	Description
`customer`	Yes	`object`	An object containing the customer's details as per the Customer Details table.
`products`	Yes	`array` of `objects`	An array of product objects, each structured as per the Product Details table.
`type`	Yes	`string`	The type of order, must be `"EXCHANGE"`.
`notes`	No	`string`	Any additional notes or special instructions for the order.
`priceDifference`	Yes	`number`	The net price difference to charge or refund (in EGP).
`handlesShipping`	Yes	`string`	Who handles shipping, `"CUSTOMER"` or `"BRAND"`.

Customer Details

Field Name	Required	Type	Description
`name`	Yes	`string`	The customer's full name (min 2 characters).
`phone`	Yes	`string`	Phone number starting with `01`, digits only, exactly 11 digits.
`address`	Yes	`string`	The customer's full address (min 2 characters).
`governorate`	Yes	`string`	The customer's governorate, one of the Valid Governorate Syntaxes.

Valid Governorate Syntaxes

6th of October
Alexandria
Aswan
Asyut
Beheira
Beni Suef
Cairo
Dakahlia
Damietta
Fayed
Fayoum
Gharbeya
Giza
Helwan
Ismailia
Kafr El Sheikh
Luxor
Matrouh
Menoufia
Minya
New Valley
North Sinai
Port Said
Qalyubia
Qena
Red Sea
Sharkeya
Sohag
South Sinai
Suez

Product Details

Please make sure all products provided to this route have their SKUs mapped with their Turuq counterparts.

Field Name	Required	Type	Description
`UID`	Yes	`string`	Turuq's unique 13-digit identifier for the product (digits only).
`quantity`	Yes	`number`	Quantity of the product (min 1).
`price`	Yes	`number`	Price per unit (in EGP).
`weight`	Yes	`number`	Weight per unit (in KG).
`type`	Yes	`string`	`"ADDED"` if the item is added in exchange, `"RETURNED"` if returned.
`defectiveQuantity`	No	`integer`	Number of defective units among the returned quantity. Applies to `"RETURNED"` products only. Cannot exceed `quantity`.

Example Payload

{
  "customer": {
    "name": "Sara Ahmed",
    "phone": "01011223344",
    "address": "123 Nile Rd., Zamalek",
    "governorate": "Cairo"
  },
  "products": [
    {
      "UID": "0001234567890",
      "quantity": 1,
      "price": 1200.00,
      "weight": 0.5,
      "type": "RETURNED",
      "defectiveQuantity": 1
    },
    {
      "UID": "0000987654321",
      "quantity": 1,
      "price": 1500.00,
      "weight": 0.4,
      "type": "ADDED"
    }
  ],
  "type": "EXCHANGE",
  "notes": "Customer returning wrong size, exchanging for larger one.",
  "totalWeight": 0.9,
  "priceDifference": 300.00,
  "handlesShipping": "BRAND"
}

Response

✅ 201 Created

The exchange order was successfully created.

Response Body

{
  "OID": "2003580071234"
}

❌ 400 Bad Request

Invalid request, schema validation failed or creation failure.

Example Error (Validation)

{
  "error": "Provided order doesn't satisfy the order schema",
  "issues": [ /* array of validation issue objects */ ]
}

Create Exchange Orders

On this page