This API is meant for integrating your current systems with Nuport. Whenever an order event is created in your system and you want to transfer that data to Nuport, you can call this API to inform Nuport to create this data in its system for further processing. This API acts as an upsert operation in that it will create an order in the system, if and only if, the internalId or referenceId does not exist already in the system. If the internalId or referenceId does, it will treat the operation as an update operation and will update the order that has the internalId or referenceId.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Create or update
This endpoint creates a new order or updates an existing one, depending on the internalId you send:
- New
internalId: a new order is created. The response is HTTP201. internalIdof one of your existing orders: that order is updated. The response is HTTP200.- No
internalId: a new order is always created.
Only your own company's orders are checked.
Read the HTTP status, not the body
The
statusCodefield inside the response body is200for both a create and an update. Use the HTTP status (201or200) to tell them apart.
Reference ID and source
- If you send an
internalIdthat exists with the samereferenceId, that order is updated. - If you send an
internalIdthat exists with a differentreferenceId, a new order is created with a numberedinternalId:<internalId>-1,<internalId>-2and so on. Use theinternalIdin the response for later calls. - A
referenceIdcan be used only once per source across your orders. If another order already has it from the same source, the request returns409and nothing is created. - If you don't send
source, the order's source isWEBSITE.
The response
The response returns the full order, in the same format as Get Order Details.
An update response also includes:
| Field | Description |
|---|---|
updatedFields | The fields whose value changed, for example ["discountAmount", "products"]. 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. |
Sending the same payload again changes nothing: the response is 200 with an empty updatedFields.
Updating an existing order
Send the same full payload you use to create the order, with the values you want to change. The update follows the same rules as Update Order: which statuses allow changes, allowed status moves, Nuport Fulfillment warehouse rules, and stock. If any part of the request fails, nothing is saved.
What is different from creating:
| Field | On an update |
|---|---|
internalId | Identifies the order. It cannot be changed. |
referenceId | Stays the same, since it identifies the order with internalId. |
products | Treated as the full list. See below. |
distributorAdvancePayment | Leave it out to keep the current amount. On a new order, leaving it out sets 0. |
distributor | name, phone, address and type work as on Update Order. distributorId and locationId are ignored; use distributor.phone and distributor.address. |
status, subStatus | Must be an allowed move from the order's current status. subStatus sent without status changes only the sub-status. |
metadata | Merged key by key with the stored metadata. Keys you don't send are kept. |
Send every product on every update
productsis the full list of products on the order. Products you leave out are removed from the order, and new ones are added. For products already on the order,quantity,price,discountanddiscountAmountare updated, and values you leave out keep their current value.
Order details can be changed while the order is Pending, On-Hold, Approved or Processing. In any other status, only status and subStatus can change. Changing any other field returns 422 listing the fields, and nothing is saved. Fields sent with their current value don't count as changes, so you can resend the full payload with only the sub-status changed.
Status
status | Dashboard label | subStatus |
|---|---|---|
REQUESTED | Pending | None |
ON_HOLD | On Hold | None (use onHoldReason) |
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 |
- Sending
APPROVEDwhen creating an order approves it straight away. - On an update, the order can only move to the statuses allowed from its current status. See the allowed moves table on Update Order.
onHoldReasonis only accepted when the request'sstatusisON_HOLD. Otherwise the request returns422before anything else is checked.
Amounts
totalDueAmount = products total (after line discounts) + delivery charge − order discount.
distributorAdvancePayment is the amount the customer has already paid. It is returned separately and is not subtracted from totalDueAmount. It must be 0 or more.
Errors
| Code | When |
|---|---|
400 | A missing field, wrong value type or invalid value, for example a negative distributorAdvancePayment; a status move that isn't allowed |
401 | Missing or wrong API key |
409 | referenceId already used by another order from the same source; a Nuport Fulfillment warehouse rule; not enough stock; another request for the same order is still in progress |
422 | onHoldReason without status ON_HOLD; unknown product; unknown pick-up location; a field change on an order whose status only allows status and subStatus (the message lists the fields) |
Validation errors are 400 here
A wrong value type or invalid value returns
400on this endpoint. Update Order returns422for the same mistakes.
If two requests for the same internalId 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
Updates appear in the order's Logs tab the same way as with Update Order, under your company's account owner name followed by via API, including products added or removed. Changes to referenceId, source and metadata are saved but not shown in the Logs tab.
