ZEzentail
SalesOrder

Create new Sales Orders in Zentail

Use this endpoint to create new Sales orders in Zentail. Once the order is in our system, you can use Zentail to manage the status and any future changes.

Integration ID

In order to create custom orders in Zentail, you will need to associate them with a Custom Order Integration. Each account will automatically create one when you create your first custom order.

This default integration will be used if the integration ID is not provided.

In order to retrieve the integration ID for each custom store, you can use the GET /customStores endpoint.

These Custom Order Integrations are really just placeholders and do not technically integrate with any external channels.

Order Statuses

You can control how the order is handled in Zential by setting the status value. Most new orders should be in either PENDING_PAYMENT or PENDING. See the table below for each status and what it means.

<Note>

Currently the API only supports one status per order. Individual line items may have different statuses after the order is created by performing various actions in the Zentail UI. </Note>

StatusExplanationAction
PENDING_PAYMENTAn order that has not yet had a verified payment.Zentail will try to reserve the inventory for up to 30 days but not actually fulfill the order or purchase labels
PENDINGA new order ready for fulfillment.Zentail will route this order to a warehouse or warehouses and send a fulfillment order where applicable.
SHIPPEDAn order that has already been shipped.Zentail will not take any action on an already shipped custom order.
CANCELLEDAn order that has been cancelled.For new custom orders, Zentail will not take any action. Channel-synced cancelled orders may arrive without line items.
RETURNEDAn order that has been successfully returned.None
REFUNDEDAn order that has been refunded.None
RETURN_REQUESTEDAn order for which a return has been requested but not yet complete.None

Shipping address

shippingAddress is optional (omit the field or send an empty object). When provided, all required address fields must be supplied. postalCode is optional outside the US, because some countries (for example the UAE) have none; omit it or send null, since an empty string is rejected.

post/salesOrder

Request

  • Base URL
    https://api.zentail.com/v1
  • Auth
    API key in header AUTHORIZATION

Request body

channelOrderIdstring required
integrationIdnumber
orderTsstring date-time
lastUpdatedTsstring date-time

Channel last-update time for upsert comparison (maps to channel_update_ts). Not the same as GET lastUpdatedTs (Zentail last_update_ts). Defaults to orderTs when omitted.

customer_notesstring
customerNamestring required
customerEmailstring
customerPhonestring
marketplaceIdstring
distributionCenterIdstring

The channel's distribution center for this order, such as the one Target Plus allocates. Lines go first to the warehouses assigned to it on the storefront.

channelWillFulfillboolean

When true, indicates the sales channel will fulfill this order.

paymentnumber required
paymentCurrencystring

ISO 4217 currency the order was placed in, e.g. MXN. Defaults to USD. A non-USD value is converted to the company's standard currency on ingest, and the original amount and rate are recorded on the order.

totalDiscountnumber
totalDiscountCurrencystring

ISO 4217 currency of totalDiscount. Defaults to USD.

totalTaxnumber
totalTaxCurrencystring

ISO 4217 currency of totalTax. Defaults to USD.

resellerCommissionnumber
requestedServiceLevelstring
status'PENDING_PAYMENT' | 'PENDING' | 'SHIPPED' | 'CANCELLED' | 'RETURNED' | 'REFUNDED' | 'RETURN_REQUESTED'

Response

Success

orderNumberstring

The unique identifier for an order in Zentail

status'PENDING_PAYMENT' | 'PENDING' | 'PARTIALLY_SHIPPED' | 'SHIPPED' | 'CANCELLED' | 'RETURNED' | 'REFUNDED' | 'RETURN_REQUESTED'
cancellationReasonstring

If the order is CANCELLED this will provide the reason for the cancellation.

channelstring

The name of the sales channel where the order was placed.

channelLabelstring

Label for the sales channel in Zentail. Some customers might have multiple instances of the same sales channel. This label is used to distinguish between them.

channelOrderIdstring

The unique identifier for the order as provided by the sales channel.

channelOrderReferenceNumberstring

An optional identifier that some sales channels provide in addition to the channelOrderId

customer_notesstring

Notes provided by the customer that placed the order

marketplaceIdstring

An identifier of the marketplace where the order was placed, if the sales channel provides multiple marketplaces.

customerNamestring

The name of the customer that placed the order

customerEmailstring

The contact email of the customer that placed the order

orderTsstring date-time

The time that the order was placed. In ISO-8601 format

lastUpdatedTsstring date-time

The time that the order was last updated in Zentail. In ISO-8601 format

requestedServiceLevelstring

The service level that was requested by the sales channel

standardServiceLevel'Standard' | 'Economy' | 'Three Day' | 'Second Day' | 'Next Day' | 'Free Shipping' | 'International Standard' | 'International Economy' | 'International Priority' | 'Freight Standard' | 'Pick Up' | 'Unknown'

The channel's service level after being standardized in Zentail. Unknown is returned if a Standard Service level can't be determined.

shipBystring date-time

The earliest of the line items' lastestShipBy timestamps. This is a read-only field. In ISO-8601 format.

fbaboolean

Indicates this is an Amazon order which was fulfilled by automatically FBA. This could be false while parts of the order are still routed to FBA if it's a multi-channel FBA order.

channelWillFulfillboolean

Whether the sales channel, rather than a merchant warehouse, is expected to fulfill this order.

primeboolean

Indicates this is a seller-fulfilled prime order.

businessOrderboolean

Indicates this is a business order.

Changes

No recorded changes to this operation across all 1 revision of this API.