Upsert Order

post https://api.nuport.io/integration/orders

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…

Loading…

Body Params

internalId

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.

distributorId

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*

deliveryDate

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.

paymentMethod

string

required

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

distributorAdvancePayment

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.

transactionId

string

A unique identifier for the payment transaction.

discount

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.

locationId

string

required

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.

autoApprove

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.

isStockTransfer

boolean

Defaults to false

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

referenceId

string

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

metadata

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.

status

string

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.

subStatus

string

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.

additionalNotes

string

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

deliveryCharge

double

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

Headers

Authorization

string

required

Defaults to API_KEY

The API key retrieved from your company settings on the Nuport platform. This should be in every header in order to facilitate proper integration.

Responses

Response body

object

statusCode

integer

Defaults to 0

string

internalId

string

authorId

string

distributorId

string

locationId

string

customDistributorLocationId

string

loadingLocationId

string

unloadingLocationId

string

deliveryPlanId

string

companyId

string

deliveryDate

string

paymentMethod

string

distributorAdvancePayment

string

totalAmount

string

totalBuyingAmount

string

transportFareAmount

string

discount

string

additionalNotes

string

status

string

subStatus

string

flagReason

string

shortId

integer

Defaults to 0

isStockTransfer

boolean

Defaults to true

parentSalesOrderId

string

copyCount

integer

Defaults to 0

staleness

integer

Defaults to 0

createdAt

string

updatedAt

string

deliveryPlan

string

distributor

object

string

name

string

disabled

boolean

Defaults to true

managerName

string

managerTitle

string

phone

string

district

string

division

string

address

string

latitude

string

longitude

string

paymentMethod

string

paymentTerms

integer

Defaults to 0

createdAt

string

updatedAt

string

accountManagerId

string

userId

string

companyId

string

shortId

integer

Defaults to 0

accountManager

string

locations

array of objects

locations

object

string

label

string

description

string

type

string

address

string

district

string

division

string

latitude

string

longitude

string

companyId

string

createdAt

string

updatedAt

string

location

object

string

label

string

description

string

type

string

address

string

district

string

division

string

latitude

string

longitude

string

companyId

string

createdAt

string

updatedAt

string

salesOrderItems

array of objects

salesOrderItems

object

integer

Defaults to 0

productId

string

salesOrderId

string

length

string

lengthUnit

string

quantity

integer

Defaults to 0

quantityUnit

string

totalWeight

string

totalWeightUnit

string

diameter

string

diameterUnit

string

thickness

string

thicknessUnit

string

weight

string

weightUnit

string

price

string

buyingPrice

string

productUnit

string

deliveredQuantity

integer

Defaults to 0

createdAt

string

updatedAt

string

product

object

transactions

array

transactions

loadingLocation

object

string

label

string

description

string

type

string

address

string

district

string

division

string

latitude

string

longitude

string

companyId

string

createdAt

string

updatedAt

string

unloadingLocation

object

string

label

string

description

string

type

string

address

string

district

string

division

string

latitude

string

longitude

string

companyId

string

createdAt

string

updatedAt

string

attachments

array

attachments

200200

400400