Upsert Order

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.

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

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 HTTP 201.
  • internalId of one of your existing orders: that order is updated. The response is HTTP 200.
  • No internalId: a new order is always created.

Only your own company's orders are checked.

📘

Read the HTTP status, not the body

The statusCode field inside the response body is 200 for both a create and an update. Use the HTTP status (201 or 200) to tell them apart.

Reference ID and source

  • If you send an internalId that exists with the same referenceId, that order is updated.
  • If you send an internalId that exists with a different referenceId, a new order is created with a numbered internalId: <internalId>-1, <internalId>-2 and so on. Use the internalId in the response for later calls.
  • A referenceId can be used only once per source across your orders. If another order already has it from the same source, the request returns 409 and nothing is created.
  • If you don't send source, the order's source is WEBSITE.

The response

The response returns the full order, in the same format as Get Order Details.

An update response also includes:

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

FieldOn an update
internalIdIdentifies the order. It cannot be changed.
referenceIdStays the same, since it identifies the order with internalId.
productsTreated as the full list. See below.
distributorAdvancePaymentLeave it out to keep the current amount. On a new order, leaving it out sets 0.
distributorname, phone, address and type work as on Update Order. distributorId and locationId are ignored; use distributor.phone and distributor.address.
status, subStatusMust be an allowed move from the order's current status. subStatus sent without status changes only the sub-status.
metadataMerged key by key with the stored metadata. Keys you don't send are kept.

🚧

Send every product on every update

products is 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, discount and discountAmount are 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

statusDashboard labelsubStatus
REQUESTEDPendingNone
ON_HOLDOn HoldNone (use onHoldReason)
APPROVEDApprovedNone
PROCESSINGProcessingNone
SHIPPEDReady to ShipNone
IN_TRANSITIn TransitNone
COMPLETEDDeliveredRequired: PAYMENT_DUE or PAYMENT_COLLECTED
FLAGGEDFlaggedRequired: RETURNED, PENDING_RETURNED, DAMAGED or LOST
CANCELLEDCancelledNone
  • Sending APPROVED when 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.
  • onHoldReason is only accepted when the request's status is ON_HOLD. Otherwise the request returns 422 before 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

CodeWhen
400A missing field, wrong value type or invalid value, for example a negative distributorAdvancePayment; a status move that isn't allowed
401Missing or wrong API key
409referenceId 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
422onHoldReason 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 400 on this endpoint. Update Order returns 422 for 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.

Body Params
string

The unique identifier for the order. This ID can be used to link your internal system's order with Nuport's internal order. This should be unique when provided. Maximum 36 characters.

string
required

The unique ID of a distributor. A distributor represents a customer, client or any other entity meant to indicate the receiver or provider of goods for your company. Note that the distributor should exist in the Nuport platform before invoking this API or else an error will be thrown. Talk to a representative to figure out how to import your distributors, customers or clients into Nuport.

products
array of objects
required

An array of Product objects to be added to an order. Each product in the array must be unique. Prices and weights can be calculated from the products stored in the Nuport platform.

products*
date-time

The date in which the order is scheduled for. If no date is provided, it is assumed that the current date that the invocation occurs is the delivery date.

string
required
Defaults to Cash, Cash On Delivery (COD), Cheque, Card, Net Banking, Bkash, Rocket, Nagad, Upay, Tap, SSL Commerz.

The payment method used for the transaction. Must match an existing payment method stored in the system. Case-insensitive and character-exact match required.

double

The advance meant to be paid to the distributor (represented by the distributorId). This amount will result in a deduction from the total amount of the order, which is calculated by the sum of all products within this order.

string

A unique identifier for the payment transaction.

int32

The discount percentage that can either be between 0 to 100. The percentage will be deducted out the total amount of the order, which is calculated by the sum of all products within this order.

double

The discount amount to be applied to the order. This value must be between 0 and the total order amount (i.e., the sum of all product prices within the order). The specified discount will be subtracted from the calculated total order value.

string

To send the delivery partner with the order, please use the preferredDeliveryPartner field and pass the delivery partner ID, for example: "preferredDeliveryPartner": "."

string

The pickUpLocationId represents the unique identifier of the Warehouse location associated with an order. Before using this field, the corresponding warehouse location must already be created on the Nuport platform. If a valid warehouse ID is provided, it will be used to determine the pickup location linked to the order. However, if the specified warehouse ID does not exist in Nuport, or if no warehouse ID is provided, the system will automatically synchronize and assign the most recently updated warehouse as the pickup location for the order.

string

The unique ID of the "drop off" location for an order. Locations for a company must be uploaded to the Nuport platform before using this field. In turn, one can decide to use the location ID to represent the location in which the order is linked to. If the location ID does not exist in Nuport, an error will be thrown. If location ID is not provided, the system will try to pull this data from the location linked to the distributor's geo-coded location.

string
enum

The source is one of the OrderSource enum values.

boolean
Defaults to false

Orders are in a REQUESTED state by default. This flag will set the order to be APPROVED when created which means that the order is eligible to be added to an optimized delivery plan.

boolean
Defaults to false

Flag to indicate if the order is stock transfer order. All orders are sales orders by default.

string

Another unique identifier for the order. Can be used, for instance, to capture the outbound delivery number. Maximum 36 characters.

json

Any extra data that the caller can provide for the product. This must be a valid JSON object and the max size of this object is 256kb.

distributor
object

Allows upserting a distributor into the system while adding this distributor to the order at the same time. If a distributorId is not provided and this field is not null, the system will try to first find a distributor with the unique phone number and attach it to the order. If it is not found, the distributor will be created using the name, phone number, and address provided so that each subsequent call will just require a lookup based on the phone number provided. Useful when distributor info is not known before hand and is only known at the point in time when creating the order.

string
enum

The status of an order. Follow the diagram to change the status of an order in a sequence that makes logical sense within your own system. Take a look at the update order API documentation to understand the status flow: https://nuport.readme.io/reference/update-order.

Allowed:
string
enum

The sub-status of an order. This sub-status will only change if the "status" field of the payload is set to PROCESSING, otherwise this field will be discarded.

Allowed:
string

Additional notes to add to the order. Max character length of 1000.

double

The delivery charge applied to the order. Must be a non-negative decimal value. The fee is included in the total order cost.

string

The user to attribute as the order creator. If omitted, falls back to the API-key's owner.

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