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.