PUT /orders/{orderId} — Update an Existing Order

Use this endpoint to correct or update an order’s details after creation. You can change customer information, the delivery address, zone, product description, item count, COD amount, and other fields — provided the order is still in an editable status. The shipping fee is always recomputed from the new government, order type, and express flag. You do not need to supply it.

Authentication

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

Path parameter

Parameter	Type	Description
`orderId`	string	The order’s MongoDB `_id` or the 6-digit `orderNumber`. Both are accepted.

Editability rules

You can only update an order while it is in an editable status — typically before a courier has been assigned. Attempting to update a locked order returns 403 FORBIDDEN. Additionally, the express shipping flag cannot be changed for orders older than 6 hours.

Restriction	Detail
Status lock	Address and order details cannot be edited after courier assignment or once the order passes the editable stage.
Express shipping	`isExpressShipping` cannot be toggled for orders created more than 6 hours ago.

Request body

Send the same fields as POST /orders. All fields are re-validated on update, so include the complete desired state rather than only the changed fields.

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 (e.g. "Nasr City - ElHay 06 (Nasr City)").

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 may inspect contents before accepting delivery.

string

Updated notes for the courier.

string

Your platform’s internal order reference.

string

Merchant pickup address ID override.

Deliver-specific fields

string

Updated product description. Required for Deliver orders.

number

Updated item count. Required for Deliver orders (positive integer).

boolean

Express delivery flag. Cannot be changed for orders older than 6 hours.

boolean

Cash on delivery flag.

number

COD amount in EGP when COD is true.

Return-specific fields

string

Description of the product(s) being returned. Required for Return orders.

number

Number of items being returned. Required for Return orders.

string

The orderNumber of the completed Deliver order this return is raised against. Required for Return orders.

string

Reason for the return. Required for Return orders.

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.

Exchange-specific fields

string

Description of the product the customer currently holds (being collected). Required for Exchange orders.

number

Number of items being collected from the customer. Required for Exchange orders.

string

Description of the replacement product being delivered. Required for Exchange orders.

number

Number of replacement items being delivered. Required for Exchange orders.

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.

Request

curl -X PUT "https://now.com.eg/api/public/v1/orders/482917" \
  -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": "20 Nile Street",
    "government": "Cairo",
    "zone": "Nasr City - ElHay 06 (Nasr City)",
    "orderType": "Deliver",
    "productDescription": "T-shirt x2",
    "numberOfItems": 2,
    "isExpressShipping": false
  }'

Response

200 — Order updated

The response returns the updated order object with the newly recomputed orderFees.

{
  "success": true,
  "data": {
    "message": "Order updated successfully.",
    "order": {
      "orderId": "66f1a2b3c4d5e6f7a8b9c0d2",
      "orderNumber": "482917",
      "orderStatus": "new",
      "orderFees": 120,
      "orderType": "Deliver",
      "isExpressShipping": false,
      "customer": {
        "fullName": "Ahmed Hassan",
        "phoneNumber": "01012345678",
        "address": "20 Nile Street",
        "government": "Cairo",
        "zone": "Nasr City - ElHay 06 (Nasr City)"
      }
    }
  }
}

Error responses

HTTP status	Code	Cause
`400`	`VALIDATION_ERROR`	Missing required fields, invalid governorate, zone not in catalog, or other field-level validation failure.
`400`	`VALIDATION_ERROR`	Express shipping flag change attempted on an order older than 6 hours.
`400`	`VALIDATION_ERROR`	Zone value does not match the delivery-zones catalog.
`401`	`UNAUTHORIZED`	API key is missing, invalid, or revoked.
`403`	`FORBIDDEN`	Order is locked — courier has been assigned or the order is past the editable stage.
`403`	`SCOPE_DENIED`	API key does not have the `orders` scope.
`403`	`MERCHANT_REQUIRED`	Company key used without `X-Merchant-Id`.
`404`	`NOT_FOUND`	No order with the given `orderId` or `orderNumber` was found.

System

Merchants

Fees

Orders

Pickups

Reference

PUT /orders/{orderId} — Update an Existing Order

Authentication

Path parameter

Editability rules

Request body

Deliver-specific fields

Return-specific fields

Exchange-specific fields

Request

Response

200 — Order updated

Error responses

​Authentication

​Path parameter

​Editability rules

​Request body

​Deliver-specific fields

​Return-specific fields

​Exchange-specific fields

​Request

​Response

​200 — Order updated

​Error responses

Authentication

Path parameter

Editability rules

Request body

Deliver-specific fields

Return-specific fields

Exchange-specific fields

Request

Response

200 — Order updated

Error responses