Update an order's amounts, products, pick-up warehouse, source, customer and status using its internalId. Send only the fields you want to change.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
How updates work
Send only the fields you want to change. Fields you leave out stay as they are. The request must contain at least one field.
Updates are all-or-nothing: if any part of the request is rejected, nothing on the order changes, including stock.
If you send values the order already has, the request succeeds and nothing changes. updatedFields comes back empty and requestRef is null. This also means you can send the full order with only one value changed.
The response
A successful response returns the full order, in the same format as Get Order Details, plus two fields:
| Field | Description |
|---|---|
updatedFields | The fields whose value changed, for example ["discountAmount", "products", "status"]. Customer changes appear as distributor.name, distributor.phone, distributor.address and distributor.type. A sub-status change appears as status. Empty when nothing changed. |
requestRef | An ID for this request, shared by every order log entry it created. null when nothing changed. |
onHoldReason is null unless the order is On-Hold.
Amounts and totals
After every change, Nuport recalculates the order total:
totalDueAmount = products total (after line discounts) + delivery charge − order discount
discountAmountis a flat order-level discount in taka. It replaces any percentage discount on the order.distributorAdvancePaymentis the amount the customer has already paid. It is returned separately and is not subtracted fromtotalDueAmount.- Changing the delivery charge on an order already sent to a courier updates Nuport only. Nothing is sent to the courier.
Products
You can change products already on the order. You cannot add or remove products with this endpoint.
For each product, send productId and only the values you want to change: quantity, price, discount (a percentage, 0 to 100) or discountAmount (taka). Values you leave out keep their current value.
Stock is only affected for orders that hold stock (Approved and later):
- Raising a quantity takes the extra units from available stock at the order's pick-up warehouse. If there isn't enough stock, the request fails with
409and nothing changes. - Lowering a quantity returns the units to available stock.
- Pending and On-Hold orders hold no stock, so their quantities can be changed freely. Stock is checked when they are approved.
Pick-up warehouse, source, reference ID and metadata
pickUpLocationIdchanges the order's Pick Up Warehouse. Send the warehouse's ID, internalId or label. It works the same as changing the warehouse in the dashboard: for an Approved order, the stock moves to the new warehouse. An unknown location returns422.- You can move an order into a Nuport Fulfillment warehouse only if that warehouse is enabled for your company; otherwise the request returns
400. From then on, the order follows the Nuport Fulfillment warehouse rules below. sourceaccepts a built-in source (such asWEBSITE,FACEBOOKorWHATSAPP) or one of your custom source slugs, in any letter case. An unknown value is saved asOTHER.referenceIdis your own ID for the order, up to 36 characters. It must not already be used by another of your orders from the same source; otherwise the request returns409and nothing is saved. If you changesourcein the same request, the check uses the new source.metadatais merged key by key with what is already stored: keys you send are added or replaced, and keys you don't send are kept.
Customer
distributor.phone decides which customer the order belongs to, the same way it does in Upsert Order:
- Phone of an existing customer: the order moves to that customer, and the delivery address becomes that customer's main address.
- New phone: a new customer is created with the name, phone, address and type you send.
- Same phone in another format (
+8801…or01…): treated as the same customer, so nothing changes.
distributor.name and distributor.type change the customer record, so the new name or type shows on all of that customer's orders, as it does in the dashboard. type accepts values such as RETAILER, DEALER or E_COMMERCE_CUSTOMER, in any letter case.
distributor.address is added to the customer's addresses and set as this order's delivery address.
If the order has no customer yet, you must send distributor.phone.
Customer changes save first
A new customer name or address is saved just before the order itself is updated. If the order update then fails (for example, not enough stock), the name or address change is kept.
Status changes
For orders in your own warehouses, status changes follow the same rules as the Nuport dashboard and trigger the same actions: stock updates, customer SMS and webhooks.
Status and sub-status values
status and subStatus are case-insensitive. The response and Get Order Details return the same values.
status | Dashboard label | subStatus |
|---|---|---|
REQUESTED | Pending | None |
ON_HOLD | On Hold | None (use onHoldReason for the reason) |
APPROVED | Approved | None |
PROCESSING | Processing | None |
SHIPPED | Ready to Ship | None |
IN_TRANSIT | In Transit | None |
COMPLETED | Delivered | Required: PAYMENT_DUE or PAYMENT_COLLECTED |
FLAGGED | Flagged | Required: RETURNED, PENDING_RETURNED, DAMAGED or LOST |
CANCELLED | Cancelled | None |
A sub-status is required when moving an order to Delivered or Flagged. For example, { "status": "FLAGGED" } on its own returns 400; send { "status": "FLAGGED", "subStatus": "RETURNED" } instead.
To change only the sub-status, send subStatus on its own. The current status is kept, for example { "subStatus": "PAYMENT_COLLECTED" } on a Delivered - Payment Due order.
Allowed moves
An order can only move to the statuses listed for its current status. COMPLETED / PAYMENT_DUE means status COMPLETED with subStatus PAYMENT_DUE.
| Current status | Can move to |
|---|---|
| Pending | APPROVED, ON_HOLD, CANCELLED |
| On Hold | APPROVED, REQUESTED, CANCELLED |
| Approved | REQUESTED, PROCESSING, SHIPPED, IN_TRANSIT, ON_HOLD, CANCELLED, COMPLETED / PAYMENT_DUE, COMPLETED / PAYMENT_COLLECTED |
| Processing | APPROVED, SHIPPED, IN_TRANSIT, ON_HOLD, CANCELLED, COMPLETED / PAYMENT_DUE, COMPLETED / PAYMENT_COLLECTED |
| Ready to Ship | PROCESSING, IN_TRANSIT, ON_HOLD |
| In Transit | APPROVED, PROCESSING, SHIPPED, CANCELLED, FLAGGED / RETURNED, FLAGGED / PENDING_RETURNED, FLAGGED / LOST, COMPLETED / PAYMENT_DUE, COMPLETED / PAYMENT_COLLECTED |
| Delivered - Payment Due | COMPLETED / PAYMENT_COLLECTED, FLAGGED / RETURNED, FLAGGED / PENDING_RETURNED |
| Delivered - Payment Collected | FLAGGED / RETURNED, FLAGGED / PENDING_RETURNED |
| Flagged - Returned | APPROVED, CANCELLED, FLAGGED / DAMAGED |
| Flagged - Pending Returned | FLAGGED / RETURNED, FLAGGED / DAMAGED, FLAGGED / LOST, COMPLETED / PAYMENT_DUE |
| Flagged - Damaged | No moves |
| Flagged - Lost | No moves |
| Cancelled | REQUESTED |
- Any other move returns
400Status cannot be changed. - Sending the order's current status and sub-status again is never an error. Nothing changes.
- Moving to
FLAGGED / RETURNEDreturns the stock, the same as a return in the dashboard. - Orders in the Nuport Fulfillment warehouse follow a shorter table instead (see below).
On-Hold reason
- To put an order On-Hold with a reason, send
status: "ON_HOLD"andonHoldReasontogether. - To change the reason on an order that is already On-Hold, send
onHoldReasonalone. - When the order leaves On-Hold, the reason is cleared.
- Sending
onHoldReasonfor an order that is not On-Hold returns409.
Which orders can be edited
Order details can be changed while the order is Pending, On-Hold, Approved or Processing.
In any other status (Ready to Ship, In Transit, Delivered, Flagged or Cancelled), only status and subStatus can change. Changing any other field returns 422 with a message listing the fields, for example Order ORD-1001 is in status COMPLETED. Only status and subStatus can be updated. Fields not allowed: discountAmount. Fields sent with their current value are not counted as changes.
Error messages about fields use API status values (COMPLETED, REQUESTED), not dashboard labels.
Orders in the Nuport Fulfillment warehouse
When an order's current pick-up warehouse is the Nuport Fulfillment warehouse, Nuport manages its fulfillment, so the API allows only these status moves:
| From \ To | Pending | Approved | On-Hold | Cancelled | Any other |
|---|---|---|---|---|---|
| Pending | — | ✅ | ✅ | ✅ | ❌ |
| Approved | ✅ | — | ✅ | ✅ | ❌ |
| On-Hold | ✅ | ✅ | — | ✅ | ❌ |
| Cancelled | ✅ | ❌ | ❌ | — | ❌ |
- Any other status move returns
409with a message using dashboard labels, for exampleStatus update from Pending to Processing is not allowed for orders in the Nuport Fulfillment warehouse. - A cancelled order can go back to Pending. No stock is reserved for Pending orders.
- Once the order is past Pending, Approved and On-Hold (for example Processing), its details can no longer be changed through the API. The request returns
409and nothing is saved. Status moves are still checked against the table above. - The order's current pick-up warehouse decides which rules apply. If you switch the warehouse in the dashboard, the API follows the new warehouse.
Errors
| Code | When |
|---|---|
400 | Empty body; the same product sent twice; the order has no customer and no distributor.phone was sent; a status move not in the allowed moves table, including Delivered or Flagged without a sub-status; a Nuport Fulfillment warehouse that isn't enabled for your company |
401 | Missing or wrong API key |
404 | No order with that internalId in your company |
409 | A Nuport Fulfillment warehouse rule; not enough stock; onHoldReason on an order that is not On-Hold; referenceId already used by another order from the same source; another update for the same order is still in progress |
422 | Unknown field or wrong value type (the message names it); a field change on an order whose status only allows status and subStatus (the message lists the fields); product not on the order; unknown pick-up location; an invalid value, such as a line discount over 100 or an unknown customer type |
Validation errors on this endpoint are 422
A wrong value type or unknown field returns
422here. Upsert Order returns400for the same mistakes.
If two updates for the same order arrive at the same moment, they are applied one after the other, or the second gets 409 with a message that the order is already being processed. Retry it.
Order logs and webhooks
- Changes appear in the order's Logs tab, one entry per changed field, under your company's account owner name followed by via API. Entries appear a few seconds after the response.
- Changes to
distributorAdvancePayment,source,referenceIdandmetadataare saved but not shown in the order's Logs tab. A customer type change is logged on the customer, not the order. - Rejected requests and requests that change nothing create no log entries.
- If you have webhooks set up, an API update sends the same status and
order.updatedevents as an edit in the dashboard.
Legacy endpoint
PATCH /integration/orders, withinternalIdin the request body, still works and follows the same status and Nuport Fulfillment warehouse rules. UsePATCH /integration/orders/{internalId}for new integrations.
