Skip to content
Zentail Developer Docs

Retrieve detailed Sales Order information for a list of orders

You call thislegacysalessales:orderssales:orders:fulfillment:selfsales:orders:inventory:selfsales:orders:self

GET
/v1/salesOrder
curl --request GET \
  --url https://api.zentail.com/v1/salesOrder \
  --header 'Authorization: Bearer <token>'

Returns very detailed information about a sales order including accounting data, tracking/package data, line items for all sales orders that match the search criteria provided. Results are sorted by the lastUpdateTs from oldest to newest.

Orders placed more than one year ago are excluded from results, unless channelOrderIds is provided.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters”
lastUpdatedTs
string format: date-time

If provided, only orders with a last updated timestamp greater than or equal to the one provided (inclusive) will be included.

status
Array
Allowed values: PENDING_PAYMENT PENDING PARTIALLY_SHIPPED SHIPPED CANCELLED RETURNED REFUNDED RETURN_REQUESTED

If provided, only orders with the given status will be included.

channelOrderIds
Array<string>

If provided, only orders with the given Channel Order Ids will be included.

orderTs
string format: date-time

If provided, only orders with a timestamp greater than or equal to the one provided (inclusive) will be included. Note: orders placed more than one year ago are excluded unless channelOrderIds is provided.

pageLength
integer
<= 100

Passing this will return the number of SalesOrder objects specified in pageLength. 100 is the maximum allowed value.

nextToken
string

The link to a requested page in the format of a full URL with the nextToken as a query parameter (all other parameters will be ignored). Use this to request the next page.

warehouseId
integer

Specifying a Zentail Warehouse Id will only return sales order line items that are routed to the corresponding warehouse.

Responses

Section titled “ Responses ”

200

Section titled “200”

Success

Media typeapplication/json
object
results

An array of SalesOrder results

Array<object>
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
pagination
object
hasNext

Indicates if there is an additional page. This is true if there is another page, otherwise it is false.

boolean
nextToken

If hasNext is true this provides the full URL for the next page of results.

string format: uri
Example
{
  "results": [
    {
      "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