Skip to content
Zentail Developer Docs

Create new Sales Orders in Zentail

You call thislegacysalessales:orderssales:orders:self

POST
/v1/salesOrder
curl --request POST \
  --url https://api.zentail.com/v1/salesOrder \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "channelOrderId": "example", "integrationId": 1, "orderTs": {}, "lastUpdatedTs": "2026-04-15T12:00:00Z", "customer_notes": "example", "customerName": "example", "customerEmail": "example", "customerPhone": "example", "marketplaceId": "example", "channelWillFulfill": true, "shippingAddress": { "name": "example", "company": "example", "addressLine1": "example", "addressLine2": "example", "city": "example", "state": "example", "postalCode": "example", "phone": "example", "email": "example", "countryCode": "example", "type": "example" }, "billingAddress": { "name": "example", "company": "example", "addressLine1": "example", "addressLine2": "example", "city": "example", "state": "example", "postalCode": "example", "phone": "example", "email": "example", "countryCode": "US", "type": "example" }, "payment": 1, "paymentCurrency": "example", "totalDiscount": 0, "totalDiscountCurrency": "example", "totalTax": 0, "totalTaxCurrency": "example", "resellerCommission": 0, "requestedServiceLevel": "example", "status": "PENDING_PAYMENT", "products": [ { "lineItemId": "example", "sku": "example", "SKU": "example", "title": "example", "quantity": 1, "unitPrice": 1, "unitPriceCurrency": "example", "tax": 1, "taxCurrency": "example", "shippingPrice": 1, "shippingPriceCurrency": "example", "giftWrapMessage": "example", "giftWrapLevel": "example", "earliestShipBy": "2026-04-15T12:00:00Z", "latestShipBy": "2026-04-15T12:00:00Z", "earliestDeliverBy": "2026-04-15T12:00:00Z", "latestDeliverBy": "2026-04-15T12:00:00Z", "requestedServiceLevel": "example" } ] }'

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.

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.

Status Explanation Action
PENDING_PAYMENT An 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
PENDING A new order ready for fulfillment. Zentail will route this order to a warehouse or warehouses and send a fulfillment order where applicable.
SHIPPED An order that has already been shipped. Zentail will not take any action on an already shipped custom order.
CANCELLED An order that has been cancelled. For new custom orders, Zentail will not take any action. Channel-synced cancelled orders may arrive without line items.
RETURNED An order that has been successfully returned. None
REFUNDED An order that has been refunded. None
RETURN_REQUESTED An 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.

Authorizations

Section titled “Authorizations”

Request Body

Section titled “Request Body”

Place all of the order details in a JSON object in the body of the request.

Media typeapplication/json
object
channelOrderId
required
string
integrationId
number
orderTs
string format: date-time
default: [object Object]
lastUpdatedTs

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.

string format: date-time
customer_notes
string
customerName
required
string
customerEmail
string
customerPhone
string
marketplaceId
string
channelWillFulfill

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

boolean
shippingAddress
object
name
string
company
string
addressLine1
string
addressLine2
string
city
string
state
string
postalCode
string
phone
string
email
string
countryCode
string
>= 2 characters <= 2 characters
type

Type of address. For example, Residential or Commercial.

string
billingAddress
object
name
required
string
company
string
addressLine1
required
string
addressLine2
string
city
required
string
state
string
postalCode
required
string
phone
string
email
string
countryCode
string
default: US >= 2 characters <= 2 characters
type

Type of address. For example, Residential or Commercial.

string
payment
required
number
paymentCurrency

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.

string
/^[A-Z]{3}$/
totalDiscount
number
0
totalDiscountCurrency

ISO 4217 currency of totalDiscount. Defaults to USD.

string
/^[A-Z]{3}$/
totalTax
number
0
totalTaxCurrency

ISO 4217 currency of totalTax. Defaults to USD.

string
/^[A-Z]{3}$/
resellerCommission
number
0
requestedServiceLevel
string
status
string
default: PENDING
Allowed values: PENDING_PAYMENT PENDING SHIPPED CANCELLED RETURNED REFUNDED RETURN_REQUESTED
products
required
Array<object>
object
lineItemId
string
sku

This is the SKU used in Zentail for the product. It may not match the SKU requested by the channel if the SKU requested was an Alias or if channel-based SKU Overrides are in use.

string
SKU

[deprecated] please use sku instead.

string
title
string
quantity
required
number
unitPrice
number
unitPriceCurrency

ISO 4217 currency of unitPrice, e.g. MXN. Defaults to USD. A non-USD value is converted to the company’s standard currency on ingest.

string
/^[A-Z]{3}$/
tax
number
taxCurrency

ISO 4217 currency of tax. Defaults to USD.

string
/^[A-Z]{3}$/
shippingPrice
number
shippingPriceCurrency

ISO 4217 currency of shippingPrice. Defaults to USD.

string
/^[A-Z]{3}$/
giftWrapMessage
string
giftWrapLevel
string
earliestShipBy
string format: date-time
latestShipBy
string format: date-time
earliestDeliverBy
string format: date-time
latestDeliverBy
string format: date-time
requestedServiceLevel
string

Responses

Section titled “ Responses ”

200

Section titled “200”

Success

Media typeapplication/json
object
orderNumber

The unique identifier for an order in Zentail

string
status
string
default: PENDING
Allowed values: PENDING_PAYMENT PENDING PARTIALLY_SHIPPED SHIPPED CANCELLED RETURNED REFUNDED RETURN_REQUESTED
cancellationReason

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

string
channel

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

string
channelLabel

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.

string
channelOrderId

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

string
channelOrderReferenceNumber

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

string
customer_notes

Notes provided by the customer that placed the order

string
marketplaceId

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

string
customerName

The name of the customer that placed the order

string
customerEmail

The contact email of the customer that placed the order

string
orderTs

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

string format: date-time
lastUpdatedTs

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

string format: date-time
requestedServiceLevel

The service level that was requested by the sales channel

string
standardServiceLevel

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

string
Allowed values: Standard Economy Three Day Second Day Next Day Free Shipping International Standard International Economy International Priority Freight Standard Pick Up Unknown
shipBy

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

string format: date-time
accounting

Information used to help with accounting

object
payment

The payment amount

number
channelTax

Tax as reported by the sales channel

number
resellerCommission

Commission taken by the sales channel

number
shippingCost

Cost of shipping

number
itemCost

Cost of the items

number
totalCost

Total cost of the order

number
revenue

Revenue of the order.

number
profit

Profit of the order

number
margin

Margin of the order

number
itemPrice

Total item price

number
shippingPrice

Total shipping price

number
refund

Total refunded if the order was partially or completely refunded

number
totalDiscount

The total discount applied on the channel

number
shippingAddress
object
name
required
string
company
string
addressLine1
required
string
addressLine2
string
city
required
string
state
string
postalCode
required
string
phone
string
email
string
countryCode
string
default: US >= 2 characters <= 2 characters
type

Type of address. For example, Residential or Commercial.

string
billingAddress
object
name
required
string
company
string
addressLine1
required
string
addressLine2
string
city
required
string
state
string
postalCode
required
string
phone
string
email
string
countryCode
string
default: US >= 2 characters <= 2 characters
type

Type of address. For example, Residential or Commercial.

string
packages

The individual packages once the order has been fulfilled

Array<object>
object
packageId

The unique identifier for the package in Zentail

number
carrier

The name of the carrier responsible for delivering the package

string
serviceLevel

The service level for the package, i.e. “2 day”

string
cost

The cost for shipping the package

number
tracking

The tracking number of the package

string
shippedTs

Timestamp at which the package has been shipped, defaulted to when the api request is sent. In ISO-8601 format

string format: date-time
rma

The RMA identifier if the package was created due to an RMA.

string
labelUrl

A URL to a shipping label for the package

string
packageWeight

The numeric weight of the package, see packageWeightUom for the units.

number
packageWeightUom

The units of measure for the packageWeight.

string
packageHeight

The height of the package in inches

number
packageWidth

The width of the package in inches

number
packageLength

The length of the package in inches

number
products
Array<object>

The line items in the package

object
sku

The SKU of a product included in the package

string
lineItemId

The unique identifier of thie line item

string
quantity

The amount of the SKU included in the package

number
products

The line items that make up the order.

Array<object>
object
lineItemId

The unique identifier for the line item in Zentail

string
channelLineItemId

The unique identifier for the line item provided by the sales channel

string
status
string
default: PENDING
Allowed values: PENDING_PAYMENT PENDING PARTIALLY_SHIPPED SHIPPED CANCELLED RETURNED REFUNDED RETURN_REQUESTED
requestedTitle

This is the title requested by the sales channel, it may not exactly match the title in Zentail.

string
requestedSku

This is the SKU requested by the sales channel, to see the SKU actually referenced by Zentail, see the SKU column.

string
sku

This is the SKU used in Zentail for the product. It may not match the SKU requested by the channel if the SKU requested was an Alias or if channel-based SKU Overrides are in use.

string
SKU

[deprecated] please use sku instead.

string
primary_image
string
mpn

This is the manufactured part number provided for the product in Zentail. This can be blank since we accept orders for products that are not in Zentail.

string
standard_product_id

This is the UPC/EAN/ISBN/GTIN provided for the product in Zentail. This can be blank since we accept orders for products that are not in Zentail.

string
title

This is the title of the Zentail product. This can be blank since we accept orders for products that are not in Zentail.

string
quantity

The amount for this line item

integer
routing_info

Information describing how this line item was routed for Warehouses to perform fulfillment.

Array<object>
object
warehouseId
integer
warehouseUniqueId

Unique identifier for the warehouse as recognized by the application. Note: This field is only provided in the response if an application is registered with Zentail as an inventory Integration or a Shipping integration or a 3PL (Third Party Logistics) software.

string
quantity

The total amount to use from this Warehouse

integer
assembledQuantity

The number of already assembled kits in the Warehouse. This is null for single sku.

integer
kitComponents

The individual components of a kit. This is null for single sku.

Array<object>
object
SKU

The component sku that is part of the kit.

string
componentQuantity

Number of component units to assembled one kit

integer
cancelQuantity
integer
shippedQuantity
integer
unitPrice
number
cost
number
totalWeight
number
packageDimensions
object
length
object
numeric
number
unit
string
width
object
numeric
number
unit
string
height
object
numeric
number
unit
string
hazmat

Whether this line item ships as hazardous material, derived from the product’s catalog hazmat attributes. null means Zentail has no usable hazmat answer for this SKU; it is not an assertion that the item is safe to ship unflagged.

object
flagged
boolean
refund
number
refundReason
string
giftWrapMessage
string
giftWrapLevel
string
earliestShipBy

In ISO-8601 format

string format: date-time
latestShipBy

In ISO-8601 format

string format: date-time
earliestDeliverBy

In ISO-8601 format

string format: date-time
latestDeliverBy

In ISO-8601 format

string format: date-time
requestedServiceLevel

Requested carrier and/or service level for the line item, else order as a whole.

string
returnOrders

Details of any return that was issued for this order.

Array<object>
object
returnOrderId

The unqiue identifier for the return order in Zentail

number
channelReturnId

The unqiue identifier for the return order in the sales channel

string
requestTs

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

string format: date-time
cancelled

Indicates the return request has been cancelled

boolean
returnItems

The line items that makeup the return order

Array<object>
object
returnOrderItemId

The unique identifier for this line item

number
SKU

The SKU that is being returned

string
quantity

The amount that is being returned

number
originalQuantity

The original quantity that was ordered

number
refundAmount

The amount of payment that is being refunded

number
fba

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.

boolean
channelWillFulfill

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

boolean
prime

Indicates this is a seller-fulfilled prime order.

boolean
businessOrder

Indicates this is a business order.

boolean
Example
{
  "status": "PENDING_PAYMENT",
  "standardServiceLevel": "Standard",
  "shippingAddress": {
    "countryCode": "US"
  },
  "billingAddress": {
    "countryCode": "US"
  },
  "products": [
    {
      "status": "PENDING_PAYMENT"
    }
  ]
}

400

Section titled “400”

Bad Request

Media typeapplication/json
object
errorCode
number
errorMessages
Array<string>
referenceId
string format: uuid
Example
{
  "errorCode": 400
}

403

Section titled “403”

Permission Denied

Media typeapplication/json
object
errorCode
number
errorMessages
Array<string>
referenceId
string format: uuid
Example
{
  "errorCode": 403
}

404

Section titled “404”

Not Found

Media typeapplication/json
object
errorCode
number
errorMessages
Array<string>
referenceId
string format: uuid
Example
{
  "errorCode": 404
}

500

Section titled “500”

Zentail Error

Media typeapplication/json
object
errorCode
number
errorMessages
Array<string>
referenceId
string format: uuid
errorMessage
string
Example
{
  "errorCode": 500
}

503

Section titled “503”

Zentail Error

Media typeapplication/json
object
errorCode
number
errorMessages
Array<string>
referenceId
string format: uuid
Example
{
  "errorCode": 503
}

Sourcesnapshot of https://app.zentail.com/api/swagger, committed at spec/v1/zentail-api.json

Built0c509dd3

API changelog