Update Order

Update an order's amounts, products, pick-up warehouse, source, customer and status using its internalId. Send only the fields you want to change.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…

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:

FieldDescription
updatedFieldsThe 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.
requestRefAn 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

  • discountAmount is a flat order-level discount in taka. It replaces any percentage discount on the order.
  • distributorAdvancePayment is the amount the customer has already paid. It is returned separately and is not subtracted from totalDueAmount.
  • 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 409 and 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

  • pickUpLocationId changes 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 returns 422.
  • 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.
  • source accepts a built-in source (such as WEBSITE, FACEBOOK or WHATSAPP) or one of your custom source slugs, in any letter case. An unknown value is saved as OTHER.
  • referenceId is 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 returns 409 and nothing is saved. If you change source in the same request, the check uses the new source.
  • metadata is 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… or 01…): 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.

statusDashboard labelsubStatus
REQUESTEDPendingNone
ON_HOLDOn HoldNone (use onHoldReason for the reason)
APPROVEDApprovedNone
PROCESSINGProcessingNone
SHIPPEDReady to ShipNone
IN_TRANSITIn TransitNone
COMPLETEDDeliveredRequired: PAYMENT_DUE or PAYMENT_COLLECTED
FLAGGEDFlaggedRequired: RETURNED, PENDING_RETURNED, DAMAGED or LOST
CANCELLEDCancelledNone

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 statusCan move to
PendingAPPROVED, ON_HOLD, CANCELLED
On HoldAPPROVED, REQUESTED, CANCELLED
ApprovedREQUESTED, PROCESSING, SHIPPED, IN_TRANSIT, ON_HOLD, CANCELLED, COMPLETED / PAYMENT_DUE, COMPLETED / PAYMENT_COLLECTED
ProcessingAPPROVED, SHIPPED, IN_TRANSIT, ON_HOLD, CANCELLED, COMPLETED / PAYMENT_DUE, COMPLETED / PAYMENT_COLLECTED
Ready to ShipPROCESSING, IN_TRANSIT, ON_HOLD
In TransitAPPROVED, PROCESSING, SHIPPED, CANCELLED, FLAGGED / RETURNED, FLAGGED / PENDING_RETURNED, FLAGGED / LOST, COMPLETED / PAYMENT_DUE, COMPLETED / PAYMENT_COLLECTED
Delivered - Payment DueCOMPLETED / PAYMENT_COLLECTED, FLAGGED / RETURNED, FLAGGED / PENDING_RETURNED
Delivered - Payment CollectedFLAGGED / RETURNED, FLAGGED / PENDING_RETURNED
Flagged - ReturnedAPPROVED, CANCELLED, FLAGGED / DAMAGED
Flagged - Pending ReturnedFLAGGED / RETURNED, FLAGGED / DAMAGED, FLAGGED / LOST, COMPLETED / PAYMENT_DUE
Flagged - DamagedNo moves
Flagged - LostNo moves
CancelledREQUESTED
  • Any other move returns 400 Status cannot be changed.
  • Sending the order's current status and sub-status again is never an error. Nothing changes.
  • Moving to FLAGGED / RETURNED returns 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" and onHoldReason together.
  • To change the reason on an order that is already On-Hold, send onHoldReason alone.
  • When the order leaves On-Hold, the reason is cleared.
  • Sending onHoldReason for an order that is not On-Hold returns 409.

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 \ ToPendingApprovedOn-HoldCancelledAny other
Pending—✅✅✅❌
Approved✅—✅✅❌
On-Hold✅✅—✅❌
Cancelled✅❌❌—❌
  • Any other status move returns 409 with a message using dashboard labels, for example Status 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 409 and 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

CodeWhen
400Empty 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
401Missing or wrong API key
404No order with that internalId in your company
409A 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
422Unknown 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 422 here. Upsert Order returns 400 for 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, referenceId and metadata are 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.updated events as an edit in the dashboard.

📘

Legacy endpoint

PATCH /integration/orders, with internalId in the request body, still works and follows the same status and Nuport Fulfillment warehouse rules. Use PATCH /integration/orders/{internalId} for new integrations.

Path Params
string
required

The internalId you set when creating the order with Upsert Order.

Body Params
distributor
object

The order's customer. Send only the parts you want to change.

products
array of objects

New quantities for products already on the order. Products cannot be added or removed. Each product can appear only once.

products
double

Order-level discount in taka, 0 or more. Replaces any percentage discount on the order.

double

Delivery charge in taka, 0 or more.

double

Amount the customer has already paid, in taka, 0 or more. Returned in the response; not subtracted from totalDueAmount.

string

Pick Up Warehouse: the ID, internalId or label of one of your warehouses, HQ or factories, or of a Nuport Fulfillment warehouse linked to your company. An unknown location returns 422.

string

Order source: a built-in value such as WEBSITE, FACEBOOK or WHATSAPP, or one of your custom source slugs. Case-insensitive. An unknown value is saved as OTHER.

string

Your own ID for the order, up to 36 characters. Must not already be used by another of your orders from the same source, otherwise 409.

string

Notes on the order. Send an empty string to clear them.

string
enum

The new order status: REQUESTED (Pending), ON_HOLD, APPROVED, PROCESSING, SHIPPED (Ready to Ship), IN_TRANSIT, COMPLETED (Delivered), FLAGGED or CANCELLED. Case-insensitive. COMPLETED and FLAGGED need a subStatus. See "Status changes" below for the allowed moves.

Allowed:
string
enum

Sub-status for Delivered orders (PAYMENT_DUE, PAYMENT_COLLECTED) and Flagged orders (RETURNED, PENDING_RETURNED, DAMAGED, LOST). Required when moving to COMPLETED or FLAGGED. Can be sent on its own; the current status is kept.

Allowed:
string

Reason the order is On-Hold, up to 250 characters. Only accepted when the order is On-Hold or is being moved to On-Hold in the same request.

Headers
string
required
Defaults to API_KEY

Bearer . Find your API key on the Nuport dashboard under Configuration > Integrations. Pressing Generate creates a new key and stops the old one from working.

Responses

Language
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json