Zentail API (v1)

Welcome to the Zentail API

This is an outline of all the currently supported Zentail API actions.

Please review or have your developers review this document and submit any feedback you may have. We’re always open to working together on new endpoints and functionality. Please let us know if you have any feedback.

Server

URL
https://api.zentail.com/v1

Authentication

zentail_auth

Security Scheme Type API Key
Header parameter name: AUTHORIZATION

Listing

Retrieve a list of listings

This endpoint is restricted to developers who have registered an application with Zentail. Please refer to our guide on building a sales channel integration to learn more about the registration process and how to use the listing endpoint.

Query Parameters

NameDescription
lastUpdateTs
string

If provided, only returns listings with an updated TS greater than the provided timestamp

skus
array

If provided, only listings with the given skus will be included.

pageLength
integer

Passing this will return the number of Listings specified, otherwise defaults to 25.

nextToken
string

Passing this will return the next page of a previous call (all other parameters will be ignored). You can find nextToken in the response from a previous GET listings call.

Responses

StatusDescription
200 successSuccess
Show common responses
Response Schema
NameDescription
results
array*
pagination
object*
cURL
Send
curl --request GET \ --url 'https://api.zentail.com/v1/listing' \ --header 'AUTHORIZATION: REPLACE_KEY_VALUE' \ --header 'content-type: application/json'
Response
{
  • "results": [
    ],
  • "pagination": {}
}
Was this section helpful?
Yes No

Retrieve a specific listing

This endpoint is restricted to developers who have registered an application with Zentail. Please refer to our guide on building a sales channel integration to learn more about the registration process and how to use the listing endpoint.

Path Parameters

NameDescription
listingid
string*

Listing ID

Responses

StatusDescription
200 successSuccess
Show common responses
Response Schema
NameDescription
id
string*

A unique identifier for this listing.

sku
string*

SKU which references the entire listing

title
string*

A "group-level" title, applies to the entire listing

description
string*

A description which applies to the entire listing

Show More
cURL
Send
curl --request GET \ --url https://api.zentail.com/v1/listing/%7Blistingid%7D \ --header 'AUTHORIZATION: REPLACE_KEY_VALUE' \ --header 'content-type: application/json'
Was this section helpful?
Yes No

Create Listing Statuses

This endpoint is restricted to developers who have registered an application with Zentail. Please refer to our guide on building a sales channel integration to learn more about the registration process and how to use the listing endpoint.

Request body schema

NameDescription
statuses
array*

Responses

StatusDescription
200 successSuccess
Show common responses
Response Schema
NameDescription
errors
array*
cURL
Send
curl --request POST \ --url https://api.zentail.com/v1/listing/status \ --header 'AUTHORIZATION: REPLACE_KEY_VALUE' \ --header 'content-type: application/json' \ --data '{"statuses":[{"listing_id":"string","sku":"string","status":"PUBLISHED","listing_url":"string","errors":[{"severity":"NOTICE","classification":"other","affected_attributes":["string"],"error":"other","message":"string"}]}]}'
Was this section helpful?
Yes No

SalesOrder

Retrieve detailed Sales Order information for a list of orders

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.

Query Parameters

NameDescription
lastUpdatedTs
string

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

status
array

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

Possible Values: PENDING_PAYMENT, PENDING, PARTIALLY_SHIPPED, SHIPPED, CANCELLED, RETURNED, REFUNDED OR RETURN_REQUESTED
channelOrderIds
array

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

orderTs
string

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

Show More

Responses

StatusDescription
200 successSuccess
Show common responses
Response Schema
NameDescription
results
array*

An array of SalesOrder results

pagination
object*
cURL
Send
curl --request GET \ --url 'https://api.zentail.com/v1/salesOrder' \ --header 'AUTHORIZATION: REPLACE_KEY_VALUE' \ --header 'content-type: application/json'
Response
{
  • "results": [
    ],
  • "pagination": {}
}
Was this section helpful?
Yes No

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.

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

Request body schema

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

NameDescription
channelOrderId
string*
integrationId
number
orderTs
string
Default: [object Object]
customer_notes
string
Show More

Responses

StatusDescription
200 successSuccess
Show common responses
Response Schema
NameDescription
orderNumber
string*

The unique identifier for an order in Zentail

status
string*
Default: PENDING
Possible Values: PENDING_PAYMENT, PENDING, PARTIALLY_SHIPPED, SHIPPED, CANCELLED, RETURNED, REFUNDED OR RETURN_REQUESTED
cancellationReason
string*

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

channel
string*

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

Show More
cURL
Send
curl --request POST \ --url https://api.zentail.com/v1/salesOrder \ --header 'AUTHORIZATION: REPLACE_KEY_VALUE' \ --header 'content-type: application/json' \ --data '{"channelOrderId":"string","integrationId":0,"orderTs":{},"customer_notes":"string","customerName":"string","customerEmail":"string","customerPhone":"string","marketplaceId":"string","shippingAddress":{"name":"string","company":"string","addressLine1":"string","addressLine2":"string","city":"string","state":"string","postalCode":"string","phone":"string","email":"string","countryCode":"US","type":"string"},"billingAddress":{"name":"string","company":"string","addressLine1":"string","addressLine2":"string","city":"string","state":"string","postalCode":"string","phone":"string","email":"string","countryCode":"US","type":"string"},"payment":0,"totalTax":0,"resellerCommission":0,"requestedServiceLevel":"string","status":"PENDING","products":[{"lineItemId":"string","SKU":"string","title":"string","quantity":0,"unitPrice":0,"tax":0,"shippingPrice":0,"giftWrapMessage":"string","giftWrapLevel":"string","earliestShipBy":"2019-08-24T14:15:22Z","latestShipBy":"2019-08-24T14:15:22Z","earliestDeliverBy":"2019-08-24T14:15:22Z","latestDeliverBy":"2019-08-24T14:15:22Z","requestedServiceLevel":"string"}]}'
Response
{
  • "orderNumber": "string",
  • "status": "PENDING",
  • "cancellationReason": "string",
  • "channel": "string",
  • "channelLabel": "string",
  • "channelOrderId": "string",
  • "channelOrderReferenceNumber": "string",
  • "customer_notes": "string",
  • "marketplaceId": "string",
  • "customerName": "string",
  • "customerEmail": "string",
  • "orderTs": "2019-08-24T14:15:22Z",
  • "lastUpdatedTs": "2019-08-24T14:15:22Z",
  • "requestedServiceLevel": "string",
  • "standardServiceLevel": "Standard",
  • "shipBy": "2019-08-24T14:15:22Z",
  • "accounting": {
    },
  • "shippingAddress": {
    },
  • "billingAddress": {
    },
  • "packages": [
    ],
  • "products": [
    ],
  • "returnOrders": [
    ],
  • "fba": true,
  • "prime": true,
  • "businessOrder": true
}
Was this section helpful?
Yes No

Get detailed Sales Order information

Returns very detailed information about a sales order including accounting data, tracking/package data, line items for the sales order with the given Zentail Order Number

Path Parameters

NameDescription
orderNumber
number*

Zentail Order Number

Responses

StatusDescription
200 successSuccess
Show common responses
Response Schema
NameDescription
orderNumber
string*

The unique identifier for an order in Zentail

status
string*
Default: PENDING
Possible Values: PENDING_PAYMENT, PENDING, PARTIALLY_SHIPPED, SHIPPED, CANCELLED, RETURNED, REFUNDED OR RETURN_REQUESTED
cancellationReason
string*

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

channel
string*

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

Show More
cURL
Send
curl --request GET \ --url https://api.zentail.com/v1/salesOrder/%7BorderNumber%7D \ --header 'AUTHORIZATION: REPLACE_KEY_VALUE' \ --header 'content-type: application/json'
Response
{
  • "orderNumber": "string",
  • "status": "PENDING",
  • "cancellationReason": "string",
  • "channel": "string",
  • "channelLabel": "string",
  • "channelOrderId": "string",
  • "channelOrderReferenceNumber": "string",
  • "customer_notes": "string",
  • "marketplaceId": "string",
  • "customerName": "string",
  • "customerEmail": "string",
  • "orderTs": "2019-08-24T14:15:22Z",
  • "lastUpdatedTs": "2019-08-24T14:15:22Z",
  • "requestedServiceLevel": "string",
  • "standardServiceLevel": "Standard",
  • "shipBy": "2019-08-24T14:15:22Z",
  • "accounting": {
    },
  • "shippingAddress": {
    },
  • "billingAddress": {
    },
  • "packages": [
    ],
  • "products": [
    ],
  • "returnOrders": [
    ],
  • "fba": true,
  • "prime": true,
  • "businessOrder": true
}
Was this section helpful?
Yes No

Cancel Sales Order in Zentail

Path Parameters

NameDescription
orderNumber
number*

Zentail Order Number

Request body schema

NameDescription
reason
string*

Reason for cancellation. Validation for reasons can be found at https://developer.zentail.com/integrations/sales-channel/cancellations

products
array*

Provide a list of items to cancel

Responses

StatusDescription
200 successSuccess
Show common responses
Response Schema
NameDescription
orderNumber
string*

The unique identifier for an order in Zentail

status
string*
Default: PENDING
Possible Values: PENDING_PAYMENT, PENDING, PARTIALLY_SHIPPED, SHIPPED, CANCELLED, RETURNED, REFUNDED OR RETURN_REQUESTED
cancellationReason
string*

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

channel
string*

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

Show More
cURL
Send
curl --request POST \ --url https://api.zentail.com/v1/salesOrder/cancel/%7BorderNumber%7D \ --header 'AUTHORIZATION: REPLACE_KEY_VALUE' \ --header 'content-type: application/json' \ --data '{"reason":"string","products":[{"lineItemId":"string","cancelQuantity":0,"restockQuantities":[{"warehouseId":0,"quantity":0}]}]}'
Was this section helpful?
Yes No

Mark Order Paid in Zentail

Path Parameters

NameDescription
orderNumber
number*

Zentail Order Number

Query Parameters

NameDescription
paidTs
string

Timestamp at which the order was paid for, defaults to when the api call is performed

Default: [object Object]

Responses

StatusDescription
200 successSuccess
Show common responses
Response Schema
NameDescription
orderNumber
string*

The unique identifier for an order in Zentail

status
string*
Default: PENDING
Possible Values: PENDING_PAYMENT, PENDING, PARTIALLY_SHIPPED, SHIPPED, CANCELLED, RETURNED, REFUNDED OR RETURN_REQUESTED
cancellationReason
string*

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

channel
string*

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

Show More
cURL
Send
curl --request POST \ --url 'https://api.zentail.com/v1/salesOrder/markPaid/%7BorderNumber%7D' \ --header 'AUTHORIZATION: REPLACE_KEY_VALUE' \ --header 'content-type: application/json'
Was this section helpful?
Yes No