--- title: "Create new Sales Orders in Zentail" method: POST path: "/salesOrder" tags: ["SalesOrder"] --- # Create new Sales Orders in Zentail `POST /salesOrder` ## Request - Base URL: `https://api.zentail.com/v1` - URL: `https://api.zentail.com/v1/salesOrder` - Auth: API key in header `AUTHORIZATION` 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. `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. ## Request body - SalesOrderPostData - `channelOrderId` string, required - `integrationId` number - `orderTs` string, date-time - `lastUpdatedTs` string, 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_notes` string - `customerName` string, required - `customerEmail` string - `customerPhone` string - `marketplaceId` string - `distributionCenterId` string: 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. - `channelWillFulfill` boolean: When true, indicates the sales channel will fulfill this order. - `shippingAddress` OptionalAddress - `name` string - `company` string - `addressLine1` string - `addressLine2` string - `city` string - `state` string - `postalCode` string - `phone` string - `email` string - `countryCode` string - `type` string: Type of address. For example, Residential or Commercial. - `billingAddress` Address - `name` string, required - `company` string - `addressLine1` string, required - `addressLine2` string - `city` string, required - `state` string - `postalCode` string, required - `phone` string - `email` string - `countryCode` string - `type` string: Type of address. For example, Residential or Commercial. - `payment` number, required - `paymentCurrency` string: 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. - `totalDiscount` number - `totalDiscountCurrency` string: ISO 4217 currency of `totalDiscount`. Defaults to USD. - `totalTax` number - `totalTaxCurrency` string: ISO 4217 currency of `totalTax`. Defaults to USD. - `resellerCommission` number - `requestedServiceLevel` string - `status` 'PENDING_PAYMENT' | 'PENDING' | 'SHIPPED' | 'CANCELLED' | 'RETURNED' | 'REFUNDED' | 'RETURN_REQUESTED' - `products` SalesOrderProductData[], required - `lineItemId` string - `sku` string: 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. - `SKU` string: [deprecated] please use `sku` instead. - `title` string - `quantity` number, required - `unitPrice` number - `unitPriceCurrency` string: 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. - `tax` number - `taxCurrency` string: ISO 4217 currency of `tax`. Defaults to USD. - `shippingPrice` number - `shippingPriceCurrency` string: ISO 4217 currency of `shippingPrice`. Defaults to USD. - `giftWrapMessage` string - `giftWrapLevel` string - `earliestShipBy` string, date-time - `latestShipBy` string, date-time - `earliestDeliverBy` string, date-time - `latestDeliverBy` string, date-time - `requestedServiceLevel` string ## Response `200` Success - SOResponseData - `orderNumber` string: The unique identifier for an order in Zentail - `status` 'PENDING_PAYMENT' | 'PENDING' | 'PARTIALLY_SHIPPED' | 'SHIPPED' | 'CANCELLED' | 'RETURNED' | 'REFUNDED' | '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. - `channelLabel` string: 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. - `channelOrderId` string: The unique identifier for the order as provided by the sales channel. - `channelOrderReferenceNumber` string: An optional identifier that some sales channels provide in addition to the `channelOrderId` - `customer_notes` string: Notes provided by the customer that placed the order - `marketplaceId` string: An identifier of the marketplace where the order was placed, if the sales channel provides multiple marketplaces. - `customerName` string: The name of the customer that placed the order - `customerEmail` string: The contact email of the customer that placed the order - `orderTs` string, date-time: The time that the order was placed. In [ISO-8601 format](/getting-started/api-basics/timestamps) - `lastUpdatedTs` string, date-time: The time that the order was last updated in Zentail. In [ISO-8601 format](/getting-started/api-basics/timestamps) - `requestedServiceLevel` string: 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. - `shipBy` string, date-time: The earliest of the line items' lastestShipBy timestamps. This is a read-only field. In [ISO-8601 format](/getting-started/api-basics/timestamps). - `accounting` object: Information used to help with accounting - `payment` number: The payment amount - `channelTax` number: Tax as reported by the sales channel - `resellerCommission` number: Commission taken by the sales channel - `shippingCost` number: Cost of shipping - `itemCost` number: Cost of the items - `totalCost` number: Total cost of the order - `revenue` number: Revenue of the order. - `profit` number: Profit of the order - `margin` number: Margin of the order - `itemPrice` number: Total item price - `shippingPrice` number: Total shipping price - `refund` number: Total refunded if the order was partially or completely refunded - `totalDiscount` number: The total discount applied on the channel - `shippingAddress` Address - `name` string, required - `company` string - `addressLine1` string, required - `addressLine2` string - `city` string, required - `state` string - `postalCode` string, required - `phone` string - `email` string - `countryCode` string - `type` string: Type of address. For example, Residential or Commercial. - `billingAddress` Address - `name` string, required - `company` string - `addressLine1` string, required - `addressLine2` string - `city` string, required - `state` string - `postalCode` string, required - `phone` string - `email` string - `countryCode` string - `type` string: Type of address. For example, Residential or Commercial. - `packages` PackageData[]: The individual packages once the order has been fulfilled - `packageId` number: The unique identifier for the package in Zentail - `carrier` string: The name of the carrier responsible for delivering the package - `serviceLevel` string: The service level for the package, i.e. "2 day" - `cost` number: The cost for shipping the package - `tracking` string: The tracking number of the package - `shippedTs` string, date-time: Timestamp at which the package has been shipped, defaulted to when the api request is sent. In [ISO-8601 format](/getting-started/api-basics/timestamps) - `rma` string: The RMA identifier if the package was created due to an RMA. - `labelUrl` string: A URL to a shipping label for the package - `packageWeight` number: The numeric weight of the package, see `packageWeightUom` for the units. - `packageWeightUom` string: The units of measure for the `packageWeight`. - `packageHeight` number: The height of the package in inches - `packageWidth` number: The width of the package in inches - `packageLength` number: The length of the package in inches - `products` object[] - `sku` string: The SKU of a product included in the package - `lineItemId` string: The unique identifier of thie line item - `quantity` number: The amount of the SKU included in the package - `products` OrderLineItem[]: The line items that make up the order. - `lineItemId` string: The unique identifier for the line item in Zentail - `channelLineItemId` string: The unique identifier for the line item provided by the sales channel - `status` 'PENDING_PAYMENT' | 'PENDING' | 'PARTIALLY_SHIPPED' | 'SHIPPED' | 'CANCELLED' | 'RETURNED' | 'REFUNDED' | 'RETURN_REQUESTED' - `requestedTitle` string: This is the title requested by the sales channel, it may not exactly match the title in Zentail. - `requestedSku` string: This is the SKU requested by the sales channel, to see the SKU actually referenced by Zentail, see the SKU column. - `sku` string: 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. - `SKU` string: [deprecated] please use `sku` instead. - `primary_image` string - `mpn` string: 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. - `standard_product_id` string: 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. - `title` string: This is the title of the Zentail product. This can be blank since we accept orders for products that are not in Zentail. - `quantity` integer: The amount for this line item - `routing_info` object[]: Information describing how this line item was routed for Warehouses to perform fulfillment. - `warehouseId` integer - `warehouseUniqueId` string: 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. - `quantity` integer: The total amount to use from this Warehouse - `assembledQuantity` integer: The number of already assembled kits in the Warehouse. This is `null` for single sku. - `kitComponents` object[]: The individual components of a kit. This is `null` for single sku. - `SKU` string: The component sku that is part of the kit. - `componentQuantity` integer: Number of component units to assembled one kit - `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` object: 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. - `flagged` boolean - `refund` number - `refundReason` string - `giftWrapMessage` string - `giftWrapLevel` string - `earliestShipBy` string, date-time: In [ISO-8601 format](/getting-started/api-basics/timestamps) - `latestShipBy` string, date-time: In [ISO-8601 format](/getting-started/api-basics/timestamps) - `earliestDeliverBy` string, date-time: In [ISO-8601 format](/getting-started/api-basics/timestamps) - `latestDeliverBy` string, date-time: In [ISO-8601 format](/getting-started/api-basics/timestamps) - `requestedServiceLevel` string: Requested carrier and/or service level for the line item, else order as a whole. - `returnOrders` ReturnOrderData[]: Details of any return that was issued for this order. - `returnOrderId` number: The unqiue identifier for the return order in Zentail - `channelReturnId` string: The unqiue identifier for the return order in the sales channel - `requestTs` string, date-time: The time that the return order was requested. In [ISO-8601 format](/getting-started/api-basics/timestamps) - `cancelled` boolean: Indicates the return request has been cancelled - `completedTs` string, date-time: The time the seller completed the return in Zentail, or null while it is still open. In [ISO-8601 format](/getting-started/api-basics/timestamps) - `returnItems` ReturnOrderDataItem[]: The line items that makeup the return order - `returnOrderItemId` number: The unique identifier for this line item - `SKU` string: The SKU that is being returned - `quantity` number: The amount that is being returned - `originalQuantity` number: The original quantity that was ordered - `refundAmount` number: The amount of payment that is being refunded - `buyerCancelRequests` BuyerCancelRequestData[]: Requests the buyer made on the sales channel to cancel some or all of this order, and the merchant's answer to each. - `buyerCancelRequestId` number: The unique identifier for the cancel request in Zentail - `channelCancelId` string: The unique identifier for the cancel request in the sales channel - `status` 'PENDING' | 'CANCELLED' | 'CLOSED': `PENDING` while the channel waits for an answer, `CANCELLED` once the channel cancelled the units, `CLOSED` once it ended any other way - `requestTs` string, date-time: The time the buyer asked to cancel. In [ISO-8601 format](/getting-started/api-basics/timestamps) - `respondByTs` string, date-time: The time the channel needs an answer by, if it set one. In [ISO-8601 format](/getting-started/api-basics/timestamps) - `items` object[]: The line items and quantities the buyer asked to cancel - `lineItemId` string - `quantity` integer - `refuseReasons` object[]: The reasons the channel accepts for refusing this request - `code` string - `label` string - `decision` 'ACCEPT' | 'REFUSE': The merchant's answer in Zentail: `ACCEPT`, `REFUSE`, or null while unanswered - `refuseReason` string: The `code` of the refuse reason the merchant picked, when the decision is `REFUSE` - `decidedTs` string, date-time: The time the merchant answered. In [ISO-8601 format](/getting-started/api-basics/timestamps) - `fba` boolean: 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. - `channelWillFulfill` boolean: Whether the sales channel, rather than a merchant warehouse, is expected to fulfill this order. - `prime` boolean: Indicates this is a seller-fulfilled prime order. - `businessOrder` boolean: Indicates this is a business order. ## Other responses - `400`: Bad Request - `403`: Permission Denied - `404`: Not Found - `500`: Zentail Error - `503`: Zentail Error --- [API](https://skmtc.dev/zentail/apis/zentail-api.md) - [All operations](https://skmtc.dev/zentail/apis/zentail-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zentail/apis/zentail-api/revisions/55e43cb43caf?raw)