POST /orders — Create a Deliver, Return, or Exchange

Use this endpoint to create a new shipping order for a customer. You can create three types of orders — Deliver to ship a package, Return to retrieve a package back from a customer, or Exchange to swap one product for another in a single trip. Before you create an order, call GET /delivery-zones and cache the zone catalog. Zone values must match the catalog exactly — free-text input is rejected.

Fees are always computed server-side. Do not send orderFees, fee, shippingFee, or amountOfFees in the request body — they are silently ignored, and the authoritative fee is returned in the response.

Authentication

Requirement	Value
API key	Required (`Authorization: Bearer nsk_live_...`)
Scope	`orders`
`X-Merchant-Id`	Required for company keys — pass `businessAccountCode` or `externalMerchantId`

Common request fields

These fields apply to all three order types.

string

required

Customer’s full name.

string

required

Customer’s primary phone number.

string

Secondary / alternative phone number.

string

required

Customer’s street address.

string

Building number.

string

Apartment number.

string

required

Destination governorate. Accepted values: Cairo, Giza, or Qalyubia.

string

required

Exact zone string from GET /delivery-zones. For example: "Nasr City - ElHay 06 (Nasr City)". Free-text values are rejected.

string

required

Type of shipment: Deliver, Return, or Exchange.

boolean

Set to true if the delivery address is a workplace rather than a residence.

boolean

When true, the customer is allowed to inspect the package contents before accepting delivery.

string

Your platform’s internal order ID. Store this to cross-reference Now Shipping orders with your own records.

string

Free-text notes for the courier (e.g. landmark, floor access instructions).

string

Merchant pickup address ID. Defaults to the merchant’s main pickup address when omitted.

Order-type fields

Deliver
Return
Exchange

Use orderType: "Deliver" to ship a package to a customer.

string

required

Description of the product(s) being delivered.

number

required

Total number of items in the shipment (positive integer).

boolean

Set to true to request express (faster) delivery. Incurs an additional fee. Default: false.

boolean

Set to true to collect cash from the customer on delivery.

number

Amount to collect in EGP when COD is true.

curl -X POST "https://now.com.eg/api/public/v1/orders" \
  -H "Authorization: Bearer nsk_live_YOUR_KEY" \
  -H "X-Merchant-Id: shop_123" \
  -H "Content-Type: application/json" \
  -d '{
    "fullName": "Ahmed Hassan",
    "phoneNumber": "01012345678",
    "address": "15 Nile Street",
    "government": "Cairo",
    "zone": "Nasr City - ElHay 06 (Nasr City)",
    "orderType": "Deliver",
    "productDescription": "T-shirt x2",
    "numberOfItems": 2,
    "isExpressShipping": false,
    "COD": true,
    "amountCOD": 500,
    "referralNumber": "ORDER-1001"
  }'

Use orderType: "Return" to retrieve a previously delivered package from a customer back to the merchant.

string

required

Description of the product(s) being returned.

number

required

Total number of items being returned (positive integer).

string

required

The orderNumber of the completed Deliver order that this return is raised against.

string

required

Reason for the return (e.g. “Wrong size”, “Damaged item”).

string

Additional notes about the return for the courier.

boolean

Set to true when only some items from the original order are being returned.

number

Number of items being returned. Required when isPartialReturn is true.

number

Total number of items in the original deliver order. Optional — used for reference.

curl -X POST "https://now.com.eg/api/public/v1/orders" \
  -H "Authorization: Bearer nsk_live_YOUR_KEY" \
  -H "X-Merchant-Id: shop_123" \
  -H "Content-Type: application/json" \
  -d '{
    "fullName": "Ahmed Hassan",
    "phoneNumber": "01012345678",
    "address": "15 Nile Street",
    "government": "Cairo",
    "zone": "Nasr City - ElHay 06 (Nasr City)",
    "orderType": "Return",
    "productDescription": "T-shirt x2",
    "numberOfItems": 2,
    "originalOrderNumber": "482917",
    "returnReason": "Wrong size",
    "isPartialReturn": false
  }'

Use orderType: "Exchange" to swap the customer’s current product with a replacement in a single courier trip.

string

required

Description of the product the customer currently holds (being collected).

number

required

Number of items being collected from the customer.

string

required

Description of the replacement product being delivered to the customer.

number

required

Number of replacement items being delivered.

boolean

Set to true when a cash difference needs to be collected or refunded during the exchange.

number

Cash difference amount in EGP when CashDifference is true.

curl -X POST "https://now.com.eg/api/public/v1/orders" \
  -H "Authorization: Bearer nsk_live_YOUR_KEY" \
  -H "X-Merchant-Id: shop_123" \
  -H "Content-Type: application/json" \
  -d '{
    "fullName": "Ahmed Hassan",
    "phoneNumber": "01012345678",
    "address": "15 Nile Street",
    "government": "Cairo",
    "zone": "Nasr City - ElHay 06 (Nasr City)",
    "orderType": "Exchange",
    "currentPD": "Blue T-shirt (L)",
    "numberOfItemsCurrentPD": 1,
    "newPD": "Blue T-shirt (XL)",
    "numberOfItemsNewPD": 1,
    "CashDifference": false
  }'

Response

201 — Order created

{
  "success": true,
  "data": {
    "message": "Order created successfully.",
    "order": {
      "orderId": "66f1a2b3c4d5e6f7a8b9c0d2",
      "orderNumber": "482917",
      "orderStatus": "new",
      "statusCategory": "new",
      "orderFees": 120,
      "orderDate": "2026-07-26T12:00:00.000Z",
      "orderType": "Deliver",
      "isExpressShipping": false,
      "amountType": "COD",
      "amount": 500,
      "customer": {
        "fullName": "Ahmed Hassan",
        "phoneNumber": "01012345678",
        "government": "Cairo",
        "zone": "Nasr City - ElHay 06 (Nasr City)"
      },
      "productDescription": "T-shirt x2",
      "numberOfItems": 2
    }
  }
}

Field	Type	Description
`order.orderId`	string	MongoDB `_id` — use this as the path parameter for update, cancel, and delete requests.
`order.orderNumber`	string	6-digit human-readable order number — use this for get and AWB requests.
`order.orderStatus`	string	Current order status (e.g. `new`).
`order.statusCategory`	string	Grouped status category.
`order.orderFees`	number	Server-computed shipping fee in EGP.
`order.amountType`	string	Payment method: `COD` (cash on delivery), `CD` (cash difference), or `NA`.
`order.amount`	number	COD or cash-difference amount in EGP.

Save both orderId and orderNumber from this response. You need orderId for mutations (update, cancel, delete) and orderNumber for read operations (get details, download AWB).

Error responses

HTTP status	Code	Cause
`400`	`VALIDATION_ERROR`	Missing required fields, invalid governorate, or zone not found in the catalog.
`401`	`UNAUTHORIZED`	API key is missing, invalid, or revoked.
`403`	`SCOPE_DENIED`	API key does not have the `orders` scope.
`403`	`MERCHANT_REQUIRED`	Company key used without `X-Merchant-Id`.
`403`	`MERCHANT_NOT_FOUND`	The merchant ID in `X-Merchant-Id` is not linked to your company.

System

Merchants

Fees

Orders

Pickups

Reference

POST /orders — Create a Deliver, Return, or Exchange

Authentication

Common request fields

Order-type fields

Response

201 — Order created

Error responses

​Authentication

​Common request fields

​Order-type fields

​Response

​201 — Order created

​Error responses

Authentication

Common request fields

Order-type fields

Response

201 — Order created

Error responses