---
title: "Add orders"
method: POST
path: "/api/v1/orders"
tags: ["Orders"]
---

# Add orders

`POST /api/v1/orders`

## Request

- Base URL: `https://api.reteno.com`
- URL: `https://api.reteno.com/api/v1/orders`
- Auth: HTTP basic
- TypeScript: <https://skmtc.dev/reteno/apis/reteno-com/docs/api/v1/orders/post.ts> (a function with typed inputs; its response is checked against the schema)

The method is used for transferring orders.<br/>Sending an order again with the same <code>externalOrderId</code> updates the existing record instead of creating a second one.<br/>The method only writes orders. To get the orders already stored in the account, set up the <a href="https://docs.reteno.com/docs/exporting-data-to-the-bigquery-tables">export to BigQuery</a> and read the <code>orders</code> and <code>orderItems</code> tables.<br/>To learn more, read <a href="https://docs.reteno.com/docs/add-orders-api-method-for-order-transferring">Order Transfer Using the Generate event API Method.</a>

## Request body

- Orders: Order list (max <b>1000</b> orders per request).
  - `orders` Order[]
    - `externalOrderId` string, required: ID of an order in the external system
    - `externalCustomerId` string: External contact id. Required if email and phone are empty
    - `totalCost` number, required: Total cost of the order
    - `status` 'INITIALIZED' | 'IN_PROGRESS' | 'DELIVERED' | 'CANCELLED' | 'ABANDONED_SHOPPING_CART', required: Order status
    - `date` string, date-time, required: Order date and time
    - `currency` string, required: Currency according to <a href="https://en.wikipedia.org/wiki/ISO_4217">ISO 4217</a>
    - `email` string: Required if externalCustomerId and phone are empty
    - `phone` string: Required if email and externalCustomerId are empty
    - `firstName` string
    - `lastName` string
    - `shipping` number
    - `discount` number
    - `taxes` number
    - `restoreUrl` string
    - `statusDescription` string
    - `storeId` string: Store ID (if you have several stores in one eSputnik account)
    - `marketId` string: Customer market/region identifier. Optional parameter. Up to 64 characters. Allowed pattern: ^[a-zA-Z0-9_-]{1,64}$
    - `source` string: Online | offline values for segmentation. If the field is empty or some other value, by default the order will be accepted as online
    - `deliveryMethod` string
    - `paymentMethod` string
    - `deliveryAddress` string
    - `additionalInfo` object
    - `items` OrderItem[]
      - `externalItemId` string, required: Product ID in the external system
      - `name` string: Product name
      - `category` string: Product category
      - `quantity` number, double, required: Number of items
      - `cost` number: Product price
      - `url` string: Link to the product page
      - `imageUrl` string: Link to the product image
      - `description` string: Short description of the product

## Response `200`

- FailedOrders: The list of orders that cannot be added or updated.<br/>The possible reasons for an order to fail:</br>- One or more required fields are empty, or the format is incorrect.</br>- All of the following optional fields are empty: <i>externalCustomerId</i>, <i>email</i>, <i>phone</i>. At least one of them is required for order creation.
  - `failedOrders` FailedOrder[]
    - `order` Order, required
      - `externalOrderId` string, required: ID of an order in the external system
      - `externalCustomerId` string: External contact id. Required if email and phone are empty
      - `totalCost` number, required: Total cost of the order
      - `status` 'INITIALIZED' | 'IN_PROGRESS' | 'DELIVERED' | 'CANCELLED' | 'ABANDONED_SHOPPING_CART', required: Order status
      - `date` string, date-time, required: Order date and time
      - `currency` string, required: Currency according to <a href="https://en.wikipedia.org/wiki/ISO_4217">ISO 4217</a>
      - `email` string: Required if externalCustomerId and phone are empty
      - `phone` string: Required if email and externalCustomerId are empty
      - `firstName` string
      - `lastName` string
      - `shipping` number
      - `discount` number
      - `taxes` number
      - `restoreUrl` string
      - `statusDescription` string
      - `storeId` string: Store ID (if you have several stores in one eSputnik account)
      - `marketId` string: Customer market/region identifier. Optional parameter. Up to 64 characters. Allowed pattern: ^[a-zA-Z0-9_-]{1,64}$
      - `source` string: Online | offline values for segmentation. If the field is empty or some other value, by default the order will be accepted as online
      - `deliveryMethod` string
      - `paymentMethod` string
      - `deliveryAddress` string
      - `additionalInfo` object
      - `items` OrderItem[]
        - `externalItemId` string, required: Product ID in the external system
        - `name` string: Product name
        - `category` string: Product category
        - `quantity` number, double, required: Number of items
        - `cost` number: Product price
        - `url` string: Link to the product page
        - `imageUrl` string: Link to the product image
        - `description` string: Short description of the product
    - `error` string, required: Error message

## Other responses

- `400`: Bad request
- `429`: Too many requests

## Changes

- **2026-11-03** `7e3e7243824f`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/reteno/apis/reteno-com/changes/api/v1/orders/post.md)

---

[API](https://skmtc.dev/reteno/apis/reteno-com.md) - [All operations](https://skmtc.dev/reteno/apis/reteno-com/llms.txt) - [OpenAPI document](https://skmtc.dev/reteno/apis/reteno-com/revisions/7e3e7243824f?raw)