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