Close
logo

Importing orders

Git RepositoryEdit on Github
Last update: 2 minutes ago by JettiReading 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 Jetti.

The POST https://api.jetti.io/api/channels/:id/manual-sale.json 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": "test@user.com"
},
"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 Jetti. 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 Jetti 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.

Jetti 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
})),
...arr,
],
[]
);

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 (https://composable.jetti.io/customchannel/variant-acknowledgement).

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, Jetti 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.

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