Orders list

Function orders/get (<http://<DOMAIN>>/api/orders/get/)

Block customer_details in Getting order list only for b2b projects

dropshipping_details block and new ownTTNPicked parameter in the delivery_data array in the order list only for b2b projects

Parameters:

token — authorization key obtained through the auth function.
from — show orders from the specified date (inclusive). Optional parameter.
Date format:
- YYYY-MM-DD
- DD.MM.YYYY
- Starting with version 3.30
- YYYY-MM-DD HH:mm:ss
- DD.MM.YYYY HH:mm:ss
to — show orders up to the specified date (inclusive). Optional parameter.
Date Format:
- YYYY-MM-DD
- DD.MM.YYYY
- Starting with version 3.30
- YYYY-MM-DD HH:mm:ss
- DD.MM.YYYY HH:mm:ss
ids[] — order numbers for display
status — show orders with selected statuses (all statuses can be downloaded via the orders/get_available_statuses function). Optional parameter. The parameter can be passed as an array or variable (status=1 or status[]=1&status[]=2, {status:1}, {status:[1, 2]}). Possible values:
- 1 - new
- 2 - in process
- 3 - delivered
- 4 - not delivered
- 6 - delivering
additionalData — boolean value (true or false). Allows to upload additional information about the order, for example, tracking number, recipient's and sender's warehouse.
Starting with version 3.30
offset — offset of user selection relative to the start (works only in combination with the limit parameter)
limit — number of orders displayed

Response:

status
- OK — orders found successfully
- EMPTY — orders not found
response.orders — array containing orders
- response.orders[i]
  - order_id — order number
  - user — user ID in the system (unique for each user)
  - delivery_name — recipient's full name
  - delivery_email — email (unique for each user within the system, duplication is not possible)
  - delivery_phone — phone number
  - delivery_city — city
  - delivery_address — delivery address (if UkrPoshta delivery option is selected, fields are separated by @ symbol)
  - delivery_type — delivery type
    - delivery_type.id — delivery type identifier in the API. You can get information about delivery options through the functions delivery/export and delivery/exportTypes..
      - 3 — Nova Post
      - 8 — Local pickup
      - 9 — UkrPoshta
      - etc. (delivery option identifiers may differ on each project)
    - delivery_type.title — delivery type name
  - delivery_price — delivery cost ("delivery_price": -1 — means that the cost of delivery is calculated at the carrier's rates)
  - comment — customer comments on the order
  - payment_type — payment type. You can get information about payment options through the payment/export and payment/exportMethods functions.
    - payment_type.id — payment type identifier in API
      - 11 — Cash on delivery
      - 12 — Cashless payment
      - 13 — In cash
      - 14 — Online payment (Stripe)
      - 15 — PayPal
      - etc.
    - payment_type.title — payment type name
  - payment_price — payment fee
  - payed — paid (1 — yes; 0 — no)
  - total_default — cost of goods (excluding discounts)
  - total_sum — total cost (including all discounts, but excluding shipping costs)
  - total_quantity — total number of items in the order
  - discount_percent — relative discount
  - discount_value — discount amount
  - coupon_code — discount coupon code
  - coupon_percent — relative discount of the coupon
  - coupon_discount_value — coupon discount amount
  - coupon_type — coupon type
    - 0 — without coupon
    - 1 — certificate for certain amount
    - 2 — reusable discount coupon
  - stat_status — order status. You can get information about all order statuses via the orders/get_available_statuses function (available since version 4.0).
    - 1 — new
    - 2 — in processing
    - 3 — delivered
    - 4 — not delivered
  - stat_created — date and time of order placement (example: 2021-04-09 12:09:01)
  - currency — currency in which the order was placed (in ISO format, for example: UAH — hryvnia, USD — dollar, EUR — euro, etc.). You can get information about all currencies through the currency/export function.
  - order_without_callback — boolean value (true or false). Whether the customer should be called back (added in version 3.32).
  - manager_id — id of the manager who processed the order
  - manager_comment — manager's comment
  - manager_discount — manager's discount
  - manager_discount_title — manager's discount name
  - delivery_country — country of delivery (if country selection is enabled on the checkout page)
  - products[i] — products in an order
    - title — product name
    - article — product SKU
    - price — product unit cost to the user
    - quantity — number of product units ordered
    - total_price — the total cost of goods, taking into account the quantity ordered
    - discount_marker — marker for used discount on the product
      - PRICE_OLD — old price / relative discount on the product
      - PAGE_DISCOUNT — category discount
      - DISCOUNT_CARD — cumulative discount
      - DISCOUNT_NONE — no discount (under conditions of promotions, etc.)
      - NONE — no discount
    - type — this parameter appeared in v4.7.0 and can contain such values (how to determine which product belongs to a set, or to which products belongs a gift can be seen on the example of this screenshot):
      - gift_parent — the product to which the gift was added
      - gift — gift itself
      - set_main — product to which the set has been added
      - set_item — product belonging to a set
    - storage_id — A unique identifier that is subsequently passed to the following parameter parent_storage_id, to indicate the relationship between items at the set/gift levels
    - parent_storage_id — If the value is null, it means that a gift or bundled items have been added to the product (this screenshot shows an example of a relation between items).
  - additional_data — additional order information (only displayed if you pass the "additionalData": true key in the body of the query)
    - np_ref — electronic invoice (hereinafter referred to as EI) ID for Nova Poshta v.2 API
    - np_number — EI number
    - sender_warehouse_ref — sender's warehouse ID in Nova Poshta API
    - recipient_warehouse_ref — recipient's warehouse ID in Nova Poshta API for the "Nova Poshta Branch" delivery method
    - recipient_address — data on the recipient's address for the “Nova Poshta Courier” delivery method:
      - recipient_address.street_id –– the recipient's street ID in Nova Poshta API
      - recipient_address.street_name –– street name
      - recipient_address.building_number –– building number
      - recipient_address.flat –– apartment number

delivery_data - array of data about delivery method
- deliveryOperatorType - type of delivery operator. Possible values: nova_poshta, ukrposht
- tnID - unique identifier of electronic shipping note
- tnNumber - number of electronic shipping note
- tnStatusName - text of delivery note status with operator
- tnTrackingUpdateDate - time of last status change at the operator
- estimatedDeliveryDate - estimated delivery date
- departure
  - sender - sender data array
  - id - unique identifier of sender in the delivery operator's database
  - title - sender's name
  - contactPerson - data array by contact person (it is passed only for deliveryOperatorType= **nova_poshta)
  - id - unique identifier of the contact person in the delivery operator's database
  - name - contact person's name
  - phone - phone number of the contact person
  - type - type of sender (the key is passed only for deliveryOperatorType= **ukrposhta) . Possible values:
    - COMPANY - Legal entity
    - PRIVATE_ENTREPRENEUR - PRIVATE COMPANY
    - INDIVIDUAL - Physical person
  - phone - sender's phone number (the key is passed only for deliveryOperatorType= **ukrposhta)
  - address
    - type - type of sender's address. Possible values: warehouse
    - geoObject - array of data about the sender's warehouse
    - id - unique identifier of the sender's city in the delivery operator's database
    - name - sender's city
warehouse (passed for type = warehouse)
id - identifier of the sender's warehouse in the delivery operator's database
name - sender's warehouse
destination
- recipient - data array about recipient
- recipient name
surname - recipient's last name
patronymic - patronymic of the recipient
phone - recipient's phone number
address - array of data about the recipient's address
type - type of sender's address. Possible values: warehouse / doors
geoObject - city data
id - unique identifier of the city in the delivery operator's database
name - recipient's city
warehouse - warehouse data (transmitted for type = warehouse)
id - unique identifier of the recipient's warehouse in the delivery operator's database
name - recipient's warehouse
street - address data for courier delivery (passed for type = doors)
id - unique street identifier in the delivery operator's database
name - street name
buildingNumber - recipient's house number (passed for type = doors)
flatNumber - number of the recipient's apartment (transmitted for type = doors)
payment - data on payment for delivery services
type - type of payment for delivery services (the key is transmitted only when ****deliveryOperatorType= ****nova_poshta)
payer - payer for delivery services
redelivery - data on return delivery
cost - amount of return delivery
payer - payer for return delivery

Note: transfer of information about the order is carried out in the language of the version of the site on which it was made.

Block in analytics response - array of data about order source and client_id

analytics - data array of the order source (utm-tags) and the customer
- utm_source - traffic source identifier;
- utm_medium - specific marketing channel;
- utm_campaign - identifier of the advertising campaign;
- utm_term - keyword identifier;
- utm_content - the identifier of the counter ad;
- google_client_id - unique user identifier.

customer_details block - only for b2b projects

In the Order List we add additional data about the customer - the group he belongs to and the type of price assigned to this group.

customer_details - an array of additional customer data for b2b projects
- group
  - id - id of the buyer group the buyer belongs to
  - title - name of the buyer group to which the buyer belongs
price_level
- id - id of price type for buyer group
- title - name of the price type for the buyer group

PUT query example

{
    "token": "c5bc0cd25647e701bc6427f3629b27b4",
    "from": "01.04.2021",
    "to": "03.04.2021",
    "additionalData": true
}

Response example

{
  "status": "OK",
  "response": {
    "orders": [
      {
        "order_id": 7,
        "user": 6,
        "delivery_name": "John Doe",
        "delivery_email": "john.doe@gmail.com",
        "delivery_phone": "+38 (055) 555-55-55",
        "delivery_city": "Kyiv",
        "delivery_address": "Branch №13: Dorohozhytska St, 4",
        "delivery_type": {
          "id": 3,
          "title": "Nova Poshta Branch"
        },
        "delivery_price": -1,
        "comment": "Order comment",
        "payment_type": {
          "id": 13,
          "title": "In cash"
        },
        "payment_price": 0,
        "payed": 0,
        "total_default": 3413,
        "total_sum": 3413,
        "total_quantity": 2,
        "discount_percent": 0,
        "discount_value": 0,
        "coupon_code": "",
        "coupon_percent": 0,
        "coupon_discount_value": 0,
        "coupon_type": 0,
        "stat_status": 2,
        "stat_created": "2021-04-09 12:09:01",
        "currency": "UAH",
        "order_without_callback": false,
        "products": [
          {
            "title": "Product 1",
            "article": "10000001",
            "price": 1001,
            "quantity": 1,
            "discount_marker": "PRICE_OLD",
            "type": "gift_parent",
            "storage_id": 41,
            "parent_storage_id": null,
            "total_price": 1001
          },
          {
            "title": "Product 13",
            "article": "10000013",
            "price": 0,
            "quantity": 1,
            "discount_marker": "DISCOUNT_NONE",
            "type": "gift",
            "storage_id": 42,
            "parent_storage_id": 41,
            "total_price": 0
          },
          {
            "title": "Test set",
            "article": "test_set_123",
            "price": 2412,
            "quantity": 1,
            "discount_marker": "PRODUCTS_SET",
            "type": "set_main",
            "storage_id": 43,
            "parent_storage_id": null,
            "total_price": 2412
          },
          {
            "title": "Product 1",
            "article": "10000001",
            "price": 1001,
            "quantity": 1,
            "discount_marker": "PRICE_OLD",
            "type": "set_item",
            "storage_id": 44,
            "parent_storage_id": 43,
            "total_price": 1001
          },
          {
            "title": "Product 5",
            "article": "10000005",
            "price": 1005,
            "quantity": 1,
            "discount_marker": "PRICE_OLD",
            "type": "set_item",
            "storage_id": 45,
            "parent_storage_id": 43,
            "total_price": 1005
          },
          {
            "title": "Product 9",
            "article": "10000009",
            "price": 1009,
            "quantity": 1,
            "discount_marker": "PRICE_OLD",
            "type": "set_item",
            "storage_id": 46,
            "parent_storage_id": 43,
            "total_price": 1009
          }
        ],
        "additional_data": {
          "np_ref": "8d8ecd29-9913-11eb-8513-b88303659df5",
          "np_number": 12345678912345,
          "sender_warehouse_ref": "0d545f63-e1c2-11e3-8c4a-0050568002cf",
          "recipient_warehouse_ref": "39931b8c-e1c2-11e3-8c4a-0050568002cf"
        }
         "analytics": {
          "utm_source": "google",
          "utm_medium": "google_cpc",
          "utm_campaign": "brand_1",
          "utm_term": (none),
          "utm_content": "banner_3",
          "google_client_id": "GA1.3.391577864.1662575866"
        }
      }
    ]
  }
}

Example of a response block with new delivery data

"delivery_data": 
{
    "deliveryOperatorType": "nova_poshta",
    "tnId": "a3a24ec9-632e-11ec-8513-b88303659df5",
    "tnNumber": "20450492106170",
    "tnStatusName": "Created",
    "tnTrackingUpdateDate": null,
    "estimatedDeliveryDate": "2021-12-24",
    "departure": {
        "sender": {
            "id": "60cd854f-580c-11eb-8513-b88303659df5",
            "title": "Private person",
            "contactPerson": {
                "id": "9bc4f232-580c-11eb-8513-b88303659df5",
                "name": "Alex J. Smith (380915554433)",
                "phone": "380915554433"
            }
        },
        "address": {
            "type": "warehouse",
            "geoObject": {
                "id": "db5c88e0-391c-11dd-90d9-001a92567626",
                "name": "Kharkiv"
            },
            "warehouse": {
                "id": "169227f4-e1c2-11e3-8c4a-0050568002cf",
                "name": "Branch №1: Pol'ova St, 67"
            }
        }
    },
    "destination": {
        "recipient": {
            "name": "Natalie",
            "surname": "Taylor",
            "patronymic": null,
            "phone": "380914443322"
        },
        "address": {
            "type": "warehouse",
            "geoObject": {
                "id": "f706237a-4078-11de-b509-001d92f78698",
                "name": "Yavoriv"
            },
            "warehouse": {
                "id": "16922828-e1c2-11e3-8c4a-0050568002cf",
                "name": "Branch №1: O. Makoveya St, 62"
            }
        }
    },
    "payment": {
        "type": "Cash",
        "payer": "Sender"
    },
    "redelivery": {
        "cost": "54000",
        "payer": "Sender"
    }
}

Example of sender address for type = doors

"address": 
{
    "type:" "doors",
    "geoObject": {
          "id": "f706237a-4078-11de-b509-001d92f78698",
          "name": "Yavoriv"
      },
     "street" : {
          "id"   : "16922828-e1c2-11e3-8c4a-0050568002cf", 
          "name" : "O. Makoveya St, 62" 
      },
      "houseNumber"   : "22/12", 
      "flatNumber"    : "16B"
}

Example of response for Ukrposhta delivery with warehouse-doors type

deliveryOperatorType=ukrposhta, departure.address=warehouse and destination.address=doors

{
    "deliveryOperatorType": "ukrposhta",
    "tnId": "d07d4f9a-444a-4da9-968f-349c50e028c0",
    "tnNumber": "0000003391590",
    "tnStatusName": "Not registred at the depot",
    "tnTrackingUpdateDate": null,
    "estimatedDeliveryDate": "2022-02-15",
    "departure": {
        "sender": {
            "type": "INDIVIDUAL",
            "id": "a4018a6e-8e86-40c4-8637-3eb71669d8ae",
            "title": "Petrov Ivan Gennadyovich",
            "phone": "380636511066"
        },
        "address": {
            "type": "warehouse",
            "geoObject": {
                "id": "10754",
                "name": "Lviv"
            },
            "warehouse": {
                "id": "79000",
                "name": "79000 Lviv, Slovats'koro St, 1"
            }
        }
    },
    "destination": {
        "recipient": {
            "name": "Tamara",
            "surname": "Perepelychko",
            "patronymic": "Anatoliivna",
            "phone": "380636511023"
        },
        "address": {
            "type": "doors",
            "geoObject": {
                "id": "10754",
                "name": "Lviv"
            },
            "street": {
                "id": "490046",
                "name": "Banakha St"
            },
            "buildingNumber": "2",
            "flatNumber": "3"
        }
    },
    "payment": {
        "payer": "Recipient"
    },
    "redelivery": {
        "cost": "43998",
        "payer": "Recipient"
    }
}

Example of a query body using offset and limit

{
    "token": "c5bc0cd25647e701bc6427f3629b27b4",
    "offset": 0,
    "limit": 2,
    "additionalData": true
}

Example of a query body for exporting individual orders

{
    "token": "c5bc0cd25647e701bc6427f3629b27b4",
    "ids": [
        5, 6
    ],
    "additionalData": true
}

Example of a query body for exporting orders by status

{
    "token": "c5bc0cd25647e701bc6427f3629b27b4",
    "status": [
        2
    ],
    "additionalData": true
}