shop.order.search
Performs order search. The 'orders' access right is required, or a user must be authorized as a courier.
Parameters
-
hash
GET
Optional
Product search condition hash string encoded for safe use in URLs. An empty hash corresponds to the 'all' hash meaning a complete list of orders, without filtering.
Hash examples & tips:
— 'id/12,23,34': IDs of orders which must be returned.
— 'search/id=123': search by one order ID.
— 'search/id=#100123': search by one formatted order ID.
— 'search/state_id=new': search by value 'new' of the 'state_id' field. To search by several values of one field with the “OR” condition, separate the values with the '||' operator; e.g., 'search/state_id=new||processing||paid'. As a condition operator instead of '=' in this example you can also use the following: '=' (matching value), '*=' (partial matching of a string value), '^=' (matching beginning of a string value), '=$' (matching ending of a string value), '!=' (no matching), math operators '<', '=', '>', '<=', '>='. You can combine search by several fields using the '&' character; e.g., 'search/state_id=new||processing&total>=100'.
— 'search/params.shipping_id=64': search of orders by the 'shipping_id' parameter with the value '64'.
— 'search/items.service_id=2': search of orders by the 'service_id' property of ordered items, with the value '2'.
— 'search/items.product_id=10': search of orders containing product with id = 10.
— 'search/promo_id=10': search of orders associated with promo campaign having id = 10. -
offset
GET
Optional
Offset relative to the beginning of the list of found orders. Non-negative integer, max. 1000. Default value: 0.
-
limit
GET
Optional
Limit on the number of found orders. Non-negative integer. Default value: 100.
-
fields
GET+POST
Optional
The list of order properties which must be returned. May contain either only the names of all order fields specified with the '*' character or also extra fields listed below, which can be added with a comma; e.g., '*,contact_full,shipping_info'.
Available extra fields:
- products: items with the 'product' key are added to 'items' sub-arrays for each of the orders in the returned result, containing detailed product-related information.
- skus: items with the 'sku' key are added to 'items' sub-arrays for each of the orders in the returned result, containing detailed information about the product variants.
- contact: items with the 'contact' key are added to the returned result, containing an array of brief customer-related information with the keys 'id', 'is_company', 'is_user', 'name', 'photo'.
- contact_full: items with the 'contact' key are added to the returned result, containing an array of detailed customer-related information including all customer’s email addresses, phone numbers and relative links to the thumbnails of the photo uploaded to the customer profile.
- state: items with the 'state' key are added to the returned result, containing an array of information about the configuration of the current order status retrieved from the store settings.
- subtotal: items with the 'subtotal' key are added to the returned result, containing a number denoting the total cost of all products within each order, without the shipping cost taken into account, expressed in the main store currency, without the currency name.
- courier: items with the 'courier' key are added to the returned result, containing an array of information about the courier selected for the order shipping.
- shipping_info: items with the 'shipping_info' key are added to the returned result, containing an array of information about the selected shipping option, including its name, cost and shipping address.
- billing_info: items with the 'billing_info' key are added to the returned result, containing an array of information about customer’s billing address.
- sales_channel: item with the 'sales_channels' key is added to the returned result containing a string denoting the sales channel via which an order has been obtained.
- order_icon: item with the 'order_icon' key is added to the returned result containing a string with the URL of an icon which is recommended to be displayed for an order.
- payment_url: payment link URL.
- stock_units: item with the 'stock_units' key is added to the returned result containing the information about the quantity units of the ordered products. -
sort
GET+POST
Optional
Description of the sort order of the returned orders by one of the fields: 'updated', 'amount', 'state_id'. The sort order description format must be the same as in SQL; e.g., "updated DESC". If no sort order is specified then the returned list of orders is sorted by 'create_datetime' field in the descending order.
-
escape
POST
Optional
Flag (0 or 1) denoting whether ordered items’ and customers’ names must be escaped for safe use in HTML code. Default value is 1.
-
format
GET
Optional
Sets response format. Available options:
json
(default),xml
.
Return value
Array with the list of found orders. Sub-arrays of individual orders contain values with the following keys:
- offset int Offset of the returned order list against the beginning of the entire order list found in the database.
- limit int Maximum number of orders that was allowed to be returned by this method call.
- count int Number of found orders.
- orders array Array of returned found orders. Each order’s sub-array contains values with the following keys:
- orders[]['id'] int Order ID.
- orders[]['id_encoded'] string Formatted order ID.
- orders[]['contact_id'] int Customer contact ID.
- orders[]['create_datetime'] datetime Order creation date and time.
- orders[]['update_datetime'] datetime Latest order update date and time.
- orders[]['state_id'] string Order status identifier.
- orders[]['total'] float Order total cost, expressed in the order currency, in the
decimal(15,4)
format. - orders[]['currency'] string Identifier of the order currency in the ISO 4217 format.
- orders[]['rate'] float Exchange rate of the order currency against the store main currency.
- orders[]['tax'] float Amount of applied tax, expressed in the order currency, in the
decimal(15,4)
format. - orders[]['shipping'] float Shipping cost, expressed in the order currency, in the
decimal(15,4)
format. - orders[]['discount'] float Discount amount, expressed in the order currency, in the
decimal(15,4)
format. - orders[]['paid_year'] int Year number from the order payment date.
- orders[]['paid_quarter'] int Year quarter number from the order payment date.
- orders[]['paid_month'] int Year month number from the order payment date.
- orders[]['paid_date'] date Order payment date in the
yyyy-mm-dd
format. - orders[]['auth_date'] date Payment authorization date in the
yyyy-mm-dd
. - orders[]['is_first'] int Flag (0 or 1) denoting customer’s first paid order.
- orders[]['unsettled'] int Flag (0 or 1) denoting whether the order is unsettled
- orders[]['comment'] string Comment to order left by the customer.
- orders[]['shipping_datetime'] datetime Date and time corresponding to the end of the period selected in the Courier shipping field when the “Edit shipping details” action is executed.
- orders[]['params'] array Order parameters array.
- orders[]['params']['shipping_id'] int Selected shipping option’s ID.
- orders[]['params']['payment_id'] int Selected payment option’s ID.
- orders[]['params']['referer_host'] string Domain of the referrer website from which the customer entered the storefront to place the order.
- orders[]['params']['departure_datetime'] datetime Date and time since which the order is considered ready for shipping.
- orders[]['params']['coupon_id'] int ID of applied discount coupon.
- orders[]['params']['sales_channel'] string Sales channel: 'backend:' (if the order was created in the store backend), 'storefront:...' (if the order was placed by a customer in the storefront), 'buy_button:' (if the order was placed via a “Buy button” widget).
- orders[]['params']['shipping_address...'] string Shipping address fields.
- orders[]['params']['shipping_name'] string Shipping option name.
- orders[]['params']['payment_plugin'] string Payment plugin identifier.
- orders[]['params']['payment_name'] string Payment option name.
- orders[]['params']['shipping_currency'] string Currency identifier, in which the shipping cost is expressed, in the ISO 4217 format.
- orders[]['params']['reduced'] int Flag (0 or 1) denoting that the stock quantities of ordered product variants were reduced during the order processing history.
- orders[]['params']['reduce_times'] int The number of times stock quantities of ordered product variants were reduced during the order processing history.
- orders[]['items'] array List of ordered product variants and services:
- orders[]['items'][]['id'] int Order item ID.
- orders[]['items'][]['order_id'] string Order ID.
- orders[]['items'][]['name'] string Order item name.
- orders[]['items'][]['product_id'] int ID of the product associated with the order item.
- orders[]['items'][]['sku_code'] string Ordered product variant’s code.
- orders[]['items'][]['sku_id'] int Ordered product variant’s ID.
- orders[]['items'][]['type'] string Order item type — 'product' or 'service'.
- orders[]['items'][]['service_id'] int Service ID if the order item is a service.
- orders[]['items'][]['service_variant_id'] int Service variant ID if the order item is a service.
- orders[]['items'][]['price'] float Order item price, expressed in the order currency, in the decimal(15,4) format.
- orders[]['items'][]['quantity'] float Order item’s quantity in the decimal(15,3) format.
- orders[]['items'][]['quantity_denominator'] int Available precision for stock quantities. Acceptable values: 1 (whole pieces), 10 (precision to tenths), 100 (precision to hundredths), 1000 (precision to thousandths).
- orders[]['items'][]['stock_id'] int ID of the stock selected for ordered variant’s stock counts update in the order properties.
- orders[]['items'][]['virtual_stock_id'] int ID of the virtual stock from which the ordered variant’s stock counts must be withdrawn.
- orders[]['items'][]['purchase_price'] float Purchase price of the order item’s associated variant, expressed in the order currency, in the decimal(15,4) format.
- orders[]['items'][]['total_discount'] float Discount amount applied to the entire quantity of the ordered product variant, expressed in the order currency, in the decimal(15,4) format.
- orders[]['items'][]['tax_percent'] float Percentage of the applied tax, if any, in the decimal(15,4) format.
- orders[]['items'][]['tax_included'] int Flag (0 or 1) denoting whether applied tax is included in the ordered product’s price.
- orders[]['items'][]['stock_unit_id'] int ID of the stock quantity unit from the ordered product variant’s properties.