Importing orders

Git RepositoryEdit on Github
Last update: a year ago by Fabio ManoReading time: 6 min

We recommend using the manual-sale.json endpoint for importing orders, rather than combining POST requests across a number of different endpoints to construct and process the sale in Onport.

The POST endpoint allows you to bundle the line item, customer and order details into a single API payload. You can also use this payload for both sending updates about an existing orders, as well as sending through the order for the first time.

An important field to set is the reference field. This will be the order name / reference the customer sees

"externalId": "1234",
"saleDefaults": {
"reference": "10001"
"customer": {
"firstName": "Test",
"lastName": "user",
"email": ""
"lineItems": [{
"externalId": "line-external-id",
"name": "line-item-name",
"quantity": 10,
"price": 20,
"taxable": true,
"variant": {
"externalId": "123"
"properties": [{
"key": "property-key",
"value": "property-value"
"shipping": [{
"code": "shipping-code",
"name": "shipping-name",
"serviceLevel": "shipping-service-level",
"price": 10
"options": {}

The endpoint returns a sales object - you can find the details of that within our API reference. You can also use the JSON schema within the sales resource to populate the saleDefaults object in the manual sale endpoint. Typically, this will be used to populate the shipping and billing addresses for the order.

The line items should be an array, detailing the item, price, quantity etc. The externalId should be the external line item ID for the object. Typically this would the the database ID for the order item within your custom system. If you want to pass in custom data for the line item, such as engraving or extended product options, you can use the properties endpoint. These values will be passed to compatible vendor systems (such as Shopify and WooCommerce) and will also be visible within the vendor portal.

The variant object connects the line item to an item within Onport. You'll need to either pass an externalId (the external unique system ID for the item in your custom system) or the SKU for the item.

Additional options are available when importing orders, such as importing items dynamically from an inventory feed. Or, updating the variant details in Onport with the payload used to create the order (e.g. if you wanted to update the variant with a new weight.

Shipping can either be passed in an a single object or as an array of objects (e.g. if there are multiple shipping lines to import).

Sale Item properties

Especially in the gifting business, it is common for Sales Order Items to carry an array of properties containing key/value pairs.

The properties can hold, for instance, gift notes to be handwritten by the vendor.

Onport makes it possible to store this information in the Sale Order Item object and pass it to the vendor's purchase order as well as displaying it in the vendor portal.

The snippet below shows an example properties array:

"properties": [{
"name": "Gift Note",
"value": "Greetings from London"

Splitting line items

Under some circumstances, you may want to split line items by quantity. For example, if there are customisation options set per quantity within a line item. When importing line items, the line item external ID should be unique. To cater for this use case, you could instead add each quantity within the line items onto separate lines, using the combination of the SKU/item ID and the index as the unique identified. When splitting in this way, they'll also appear as split across multiple line items on the vendors store.

import { range } from 'lodash';
const lineItems = channelItems.reduce(
(arr, channelItem) => [
// Loop through each quantity using the range function in lodash. This will split each quantity on to a
// seperate line item
...range(1, channelItem.quantity + 1, (index) => ({
// Generate a unique ID based on the SKU of the item + the index
externalId: `${channelItem.sku}_${index}`,
// Set the quantity to 1, as each line item is being split by quantity
quantity: 1,
properties: [
key: `Unique property for item ${index}`,
// TODO Add the additional line item values here, SKU, etc

Autoconnecting by SKU

If there are items in the order, not yet acknowledged as being on your channel, you can pass in a falg in the options object to automatically acknowledge these items. Once acknowledged, invenotry and pricing updates will then start to sync for the variant. You can also manually acknowledge items in our acknowledge-variants.json endpoint (

You should also use this flag if you want to automatically connect by SKU (set under lineItems -> variant -> sku)

"options": {
"findOrCreateChannelVariant": true

Manually Specifying Routing

By default, while importing orders, Onport is able to route purchase orders automatically according to the rules set up in the application.

However, in specific cases, it is possible to define granular inhouse/dropship routing rules at a line item level, while sending the order to the manual-sale.json endpoint or asynchronous endpoint.

This is carried out by adding the following properties to each line item:

In-House Fulfillment

"orderRouting": "manual",
"manualRouting": "fulfill",
"warehouseId": :id

The :id value will need to be replaced with the Warehouse ID.

Dropship Routing

"orderRouting": "manual",
"manualRouting": "dropship",
"dropshipProviderId": :id

The :id value will need to be replaced with the ID of the Dropship Provider fulfilling the line item.

Specifying Fulfillment Location

Within the same order, each line item can be fulfilled from separate locations. This can be done in different ways depending on which properties are available.

Using dropship provider address ID

If the dropship provider address ID is known, this field can be passed along with each line item:

"lineItems": [{
"dropshipProviderAddressId": "dropship-provider-address-id-1"
"dropshipProviderAddressId": "dropship-provider-address-id-2"

Onport will then route this item via the dropship provider that matches the specified address.

Using external ID

If the dropship provider address ID is not available, it is possible to manually set the fulfillment location using the external ID. This requires the externalId field to be populated when creating the dropship provider addresses within Onport. externalId is a string field within the dropship-provider-address resource that can be used to set a custom identifier for dropship provider addresses without requiring the use of Onport's internal IDs.

To use the external ID, the dropshipProviderScope option must be set to external in the options field:

"options": {
"dropshipProviderScope": "external"

Then, for each line item, the dropshipProviderAddressId should be populated with an external ID, which needs to match the external ID of an existing dropship provider address within Onport:

"lineItems": [{
"dropshipProviderAddressId": "manually-specified-fulfillment-location-1"
"dropshipProviderAddressId": "manually-specified-fulfillment-location-2"

Onport will then identify the dropship providers that match the provided external IDs and route the orders accordingly.

๐Ÿ“ฆ Shipping โ€” Previous
Generating Shipping Labels
Next โ€” ๐Ÿ’ป Custom channel
Importing Products