# Instant Order Search Export (ISE) ## Overview Export order data for your account from the 2Checkout platform. Instant Order Search Export (ISE) works as a data portability service designed to let you export order information from your 2Checkout account packaged as either CSV or XML files. Most orders should be available in the search results almost instantly, but there might be situations where it might take up to 15 minutes for an order to be available in search results. ## Availability ISE is available to all 2Checkout accounts. ## Method and URL GET or POST: ? ## Parameters for eStore orders 2Checkout captures the parameters you send and exports the data to the client. | Field | Description | Required | Used in HASH validation | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- | ----------------------- | | MERCHANT | Your 2Checkout merchant code. The merchant code and secret key for your account are available [here](https://secure.avangate.com/cpanel/account_settings.php). | Required, cannot be empty | YES | | STARTDATE | The start date, in format Y-m-d (ex: 2010-05-22) | Required, cannot be empty | YES | | ENDDATE | The end date, in format Y-m-d (ex: 2010-05-22) | Required, cannot be empty | YES | | ORDERSTATUS |

The order status:
- ALL
- COMPLETE
- REFUND
- UNFINISHED
- COMPLETE\_AND\_REFUND
- REVERSED

| Required, cannot be empty | YES | | REQ\_DATE |

The time of request (UTC), in format YmdHis:
Y = year, 4 digits
m = month, 2 digits
d = day, 2 digits
H = hour, 2 digits
i = minute, 2 digits
s = seconds, 2 digits

| Required, cannot be empty | YES | | PRODUCT\_ID | Unique, system-generated 2Checkout product identifier | Required, can be empty | YES | | COUNTRY\_CODE | Two letter country code (download a complete list from via this [link](https://secure.avangate.com/cpanel/help.php?view=resources)) | Required, can be empty | YES | | FILTER\_STRING | Query value that depends on the value of the FILTER\_FIELD. See FILTER\_FIELD for more info. | Required, can be empty | YES | | FILTER\_FIELD |

Filter field designed to lower the search result. Use in conjunction with FILTER\_STRING.
Possible values:
- REFNO (2Checkout order reference)
- REFNOEXT (vendor order reference)
- NAME (customer name or company)
- EMAIL (customer billing email)
- COUPONCODE (order coupon code)
- AFFLIATEID (orders from a specific affiliate)
To search only a particular order, the value of FILTER\_FIELD needs to be REFNO, while the value of the FILTER\_STRING should be the unique order reference from the 2Checkout system.

| Required, can be empty | YES | | HASH | The SHA256 HMAC key for the request | Required | N/A | | SIGNATURE\_ALG | The hashing algorithm used to authenticate the request. To use SHA2 or SHA3 for auth, simply pass **sha256** or **sha3-256** as value for the **SIGNATURE\_ALG** parameter. | Required | NO | | INCLUDE\_DELIVERED\_CODES | Includes delivered codes | Optional | NO | | INCLUDE\_FINANCIAL\_DETAILS | Includes financial details. (Net profit, DIS COST, DIS Profit) | Optional | NO | | INCLUDE\_EXCHANGE\_RATES | Includes exchange rates | Optional | NO | | INCLUDE\_PRICING\_OPTIONS | Includes pricing options (pricing option text, pricing options value) | Optional | NO | | EXPORT\_FORMAT |

This parameter controls the format of file used for the export process. Possible values:
- CSV
- XML

| Optional | NO | | INCLUDE\_CLIENTIP | Include end user IP address | Optional | NO | | INCLUDE\_NETINCOMEPERPRODUCT | Include net income per product | Optional | NO | | USE\_REPORT\_MODE |

- YES - the search process returns orders in accordance with the date when they reached the Finished status. Finish date needs to be within the STARTDATE and ENDDATE interval.
- NO (default) - the search process returns orders in accordance with the date when they were placed. Place order date need to be within the STARTDATE and ENDDATE interval.

| Optional | NO | | EXPORT\_TEST\_ORDERS |

Possible values:
- YES - Include test orders along with real order.
- NO (default) - Do not include test order data and export only details for actual purchases.
- ONLY - Export only test order data.

| Optional | NO | | EXPORT\_TEMPLATE\_ID |

Return order search information specific to templates configured for Order Search Export by using their unique IDs. For eStore, navigate to Order search () under Orders \&customers and make sure that the eStore orders tab is selected. Run a search to identify the orders you're looking for, and on the right hand side of the screen click the Export button, and the Edit templates link in the popup dialog box. The template identifier is visible in the URL as the IdTemplate parameter.
When using EXPORT\_TEMPLATE\_ID, you can exclude INCLUDE\_DELIVERED\_CODES, INCLUDE\_FINANCIAL\_DETAILS, INCLUDE\_EXCHANGE\_RATES, INCLUDE\_PRICING\_OPTIONS, INCLUDE\_CLIENTIP and INCLUDE\_NETINCOMEPERPRODUCT, if the Order search Export template already contains such information.
Data in the Order Search Export template takes precedence over INCLUDE\_DELIVERED\_CODES, INCLUDE\_FINANCIAL\_DETAILS, INCLUDE\_EXCHANGE\_RATES, INCLUDE\_PRICING\_OPTIONS, INCLUDE\_CLIENTIP and INCLUDE\_NETINCOMEPERPRODUCT - this means that these parameters are ignored if they overlap with template fields.

| Optional | NO | | INCLUDE\_CHARGEBACKS\_STATUS\_AND\_REASON |

Includes the status and reason provided for chargebacks. Available values:
- YES
- NO

| Optional | NO | | EXPORT\_TIMEZONE\_REGION |

Controls the timezone provided in STARTDATE and ENDDATE fields. Example: 'Europe/London'. Check the values accepted as strings here.
If not provided, the timezone used is the API timezone set up in Control Panel. If no API timezone is set, the default platform timezone is used. Daylight saving time is considered in the timezone region parameter.

| Optional | NO | ### Parameters for Partner orders | Field | Description | Required | Used in HASH validation | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ----------------------- | | MERCHANT | Your 2Checkout merchant code. The merchant code and secret key for your account are available [here](https://secure.avangate.com/cpanel/account_settings.php). | Required, cannot be empty | YES | | STARTDATE | The start date, in format Y-m-d (ex: 2010-05-22) | Required, cannot be empty | YES | | ENDDATE | The end date, in format Y-m-d (ex: 2010-05-22) | Required, cannot be empty | YES | | ORDERSTATUS |

The order status:
- REFUNDED
- PENDING\_APPROVAL
- CANCELED
- REJECTED
- COMPLETE
- AWAITING\_PAYMENT
- DELIVERY\_NEEDS\_INFO

| Required, cannot be empty | YES | | REQ\_DATE |

The time of request (UTC), in format YmdHis:
Y = year, 4 digits
m = month, 2 digits
d = day, 2 digits
H = hour, 2 digits
i = minute, 2 digits
s = seconds, 2 digits

| Required, cannot be empty | YES | | PRODUCT\_ID | Unique, system-generated 2Checkout product identifier. | Required, can be empty | YES | | PARTNER\_CODE | Partners codes can be viewed by selecting each partner from [here](https://secure.2checkout.com/cpanel/partners.php?list). | Required, can be empty. If empty, default is all. Supports multiple codes per message, separated by a comma. | NO | | SUBSCRIPTION\_TYPE |

Subscription types:
- NEW
- RENEWAL
- UPGRADE

| Required, can be empty. If empty, default is all. | NO | | SOURCE |

Source of the partner order:
- PARTNER
- VENDOR

| Required, can be empty. If empty, default is all. | NO | | PRICELIST\_CODE | Price lists codes can be viewed by selecting each price list from [here](https://secure.2checkout.com/cpanel/price_lists.php). | Required, can be empty. | NO | | COUNTRY\_CODE | Two letter country code (download a complete list from this [link](https://secure.2checkout.com/cpanel/help.php?view=resources)) | Required, can be empty. | YES | | FILTER\_STRING | Query value that depends on the value of the FILTER\_FIELD. See FILTER\_FIELD for more info. | Required, can be empty. | YES | | FILTER\_FIELD |

FILTER\_FIELD is designed to lower the search result. Use in conjunction with FILTER\_STRING.
Possible values:
- REFNO (2Checkout reference number)
- PARTNER\_REFNO (partner reference number)
- PARTNER\_INVOICE\_NUMBER
- SKU
To search only a particular order, the value of FILTER\_FIELD needs to be REFNO, while the value of the FILTER\_STRING should be the unique order reference from the 2Checkout system.

| Required, can be empty. In conjunction with FILTER\_STRING. | YES | | HASH | The SHA256 HMAC key for the request. | Required | N/A | | SIGNATURE\_ALG | The hashing algorithm used to authenticate the request. To use SHA2 or SHA3 for auth, simply pass sha256 or sha3-256 as value for SIGNATURE\_ALG parameter. | Required | NO | | EXPORT\_FORMAT |

This parameter controls the format of file used for the export process. Possible values:
- CSV
- XML

| Optional | NO | | USE\_REPORT\_MODE |

- YES - the search process returns orders in accordance with the date when they reached the Finished status. Finish date needs to be within the STARTDATE and ENDDATE interval.
- NO (default) - the search process returns orders in accordance with the date when they were placed. Place order date needs to be within the STARTDATE and ENDDATE interval.

| Optional | NO | | PARTNER\_INVOICE\_DATE | The date in format Y-m-d (ex: 2010-05-22). It filters the results and returns orders in accordance with the date when a partner invoice was generated for these orders. | Optional | NO | | EXPORT\_TEMPLATE\_ID |

Return order search information specific to templates configured for Order Search Export by using their unique IDs. For Partner Orders, navigate to Order search () under Orders \&customers and make sure that the Partner orders tab is selected. Run a search to identify the orders you're looking for, and on the right hand side of the screen click the Export button, and the Edit templates link in the popup dialog box. The template identifier is visible in the URL as the IdTemplate parameter.
When using EXPORT\_TEMPLATE\_ID, you can exclude INCLUDE\_DELIVERED\_CODES, INCLUDE\_FINANCIAL\_DETAILS, INCLUDE\_EXCHANGE\_RATES, INCLUDE\_PRICING\_OPTIONS, INCLUDE\_CLIENTIP, and INCLUDE\_NETINCOMEPERPRODUCT, if the Order search Export template already contains such information.
Data in the Order Search Export template takes precedence over INCLUDE\_DELIVERED\_CODES, INCLUDE\_FINANCIAL\_DETAILS, INCLUDE\_EXCHANGE\_RATES, INCLUDE\_PRICING\_OPTIONS, INCLUDE\_CLIENTIP and INCLUDE\_NETINCOMEPERPRODUCT - this means that these parameters are ignored if they overlap with template fields.

| Optional | NO | | CHANNEL\_TYPE |

Specifies if the ISE should return eStore orders or Partner orders. Possible values:
- ECOMMERCE (default)
- PARTNER

| Optional | NO | ## Requirements ### HASH validation * To validate the SHA256 hash signature, you're required to include all mandatory parameters. 2Checkout throws an error if one of these parameters is missing. * Include PRODUCT\_ID and COUNTRY\_CODE. Use empty values to return all results. * The interval between STARTDATE and ENDDATE can not be greater than 45 days (for performance purposes). * Use UTC for the time zone of REQ\_DATE. The difference between the value of REQ\_DATE and the moment when you send the request to 2Checkout must be smaller than 5 minutes, or 2Checkout will respond with the 'Request expired' error message. ## Authentication Authenticate requests using: * HASH. This is a SHA256 Hash-based message authentication code (HMAC) that you create using your account's secret key and the parameters marked as mandatory for HASH validation. To build the HMACSHA256{} source string, prepend each value with its own length in bytes. Use **0** for **null** or **empty** values **without prepending their length**. However, when the value is **0** (zero), you do need to prepend its length (**1**). Note that for UTF-8 characters the length in bytes can be longer than the string length. * REQ\_DATE. Use UTC time zone. Optional: the authentication can be restricted by IP or range of IPs from firewall (Accounts settings ->User access -> Firewall) for the special service user. If the IP from where you make the request is not configured in 2Checkout, the authentication fails. ### Response Provided that your request is valid, you will receive the information in line, in the requested format (parameter EXPORT\_FORMAT), with HTTP code 200. ## Errors 2Checkout returns errors in XML format. This includes authentication errors and no results after a search message. 2Checkout throws errors with a 400 HTTP error code for the result page. Sample response XML: ```xml 1 Request has expired 20110209144927 2f69dda102b2a29e077452f64f4dca1f ``` The XML can be validated using the same SHA256 HMAC signature algorithm, using these fields: RESPONSE\_CODE, RESPONSE\_MSG, RESPONSE\_DATE and using the account hash key. | Field | Description | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | RESPONSE\_CODE | The response code (two digits) | | RESPONSE\_MSG | A more explanatory response message | | RESPONSE\_DATE |

The time of response (UTC), in format YmdHis:
Y = year, 4 digits
m = month, 2 digits
d = day, 2 digits
H = hour, 2 digits
i = minute, 2 digits
s = seconds, 2 digits

| Possible error codes and values: | Message code | Message description | Resolution | | ------------ | --------------------------------------------- | --------------------------------------------------------------------------------------------- | | 0 | No result found for the searched criteria | Check search filters. | | 1 | Request has expired | Check REQ\_DATE. | | 2 | Not all the mandatory variables are present | See required fields above. | | 3 | The selected interval is greater than 45 days | Check STARTDATE and ENDDATE. | | 4 | MERCHANT is missing or incorrect | Check MERCHANT value. | | 5 | ORDERSTATUS is missing or invalid | Check ORDERSTATUS value. | | 6 | Ip not allowed by firewall | Check firewall rules for special service user. | | 7 | HASH is missing or invalid | Double check how SHA256 hash signature is calculated. | | 8 | REQ\_DATE is missing or invalid | REQ\_DATE is missing or not in the right format. | | 9 | FILTER\_FIELD is invalid | Check possible values of FILTER\_FIELD. | | 10 | FILTER\_STRING is missing or invalid | FILTER\_FIELD is set to limit search. Check FILTER\_STRING value. | | 11 | Module is not active for your account | Instant Search Export service is not active for your account. Please contact account manager. | | 12 | EXPORT\_TEMPLATE\_ID is invalid | Check the EXPORT\_TEMPLATE\_ID value. | | 13 | Country code is incorrect. | Provide a valid country code. | | 14 | Provided time zone region is incorrect | Check EXPORT\_TIMEZONE\_REGION value. | | 15 | PARTNER\_CODE is invalid | Check “Partner code” in **View partner** section in cPanel. | | 16 | PRICELIST\_CODE is invalid | Check “Price list code” in **Edit price list** section in cPanel. | Code sample for eStore orders {% code title="ise\_example.php" %} ```php $val) { $$key = $val; /* get values */ if (!in_array($key, $not_in_hash)) { if (is_array($val)) { $result .= ArrayExpand($val); } else { $size = strlen(StripSlashes($val)); $result .= $size . StripSlashes($val); } } } //*********Calculated HMAC_SHA256 signature:********* $hash = hash_hmac($algo, $result, $secret_key); $link_params['HASH'] = $hash; $get_vars = http_build_query($link_params, '', '&'); //*********MAKE POST CALL to get ISE results********* $ch = curl_init($base_link . '?' . $get_vars); curl_setopt($ch, CURLOPT_POSTFIELDS, null); curl_setopt($ch, CURLOPT_POST, false); curl_setopt($ch, CURLOPT_HTTPGET, true); curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1); curl_setopt($ch, CURLOPT_HEADER, 0); //**use the following 3 lines only if you have a proxy set!** //curl_setopt($ch, CURLOPT_HTTPPROXYTUNNEL, 1); //curl_setopt($ch, CURLOPT_PROXY, 'YOUR_PROXY_ADDRESS:PORT'); //curl_setopt($ch, CURLOPT_PROXYUSERPWD, $proxy_user.':'.$proxy_pass); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); // RETURN THE CONTENTS OF THE CALL curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true); $responseData = curl_exec($ch); $headerCode = curl_getinfo($ch, CURLINFO_HTTP_CODE); $contentType = curl_getinfo($ch, CURLINFO_CONTENT_TYPE); //echo 'Curl error: '.curl_error($ch); curl_close($ch); //*********PROCESS RESULTS********* if ($headerCode == 200) { // do something with the csv or xml received //the format of the export file is set using $link_params['EXPORT_FORMAT'] $exportType = strtolower($link_params['EXPORT_FORMAT']); $headerType = 'Content-type: application/' . $exportType . ';charset=UTF-8'; $headerDisposition = 'Content-Disposition: attachment; filename="ise.' . $exportType . '"'; header($headerType); header($headerDisposition); echo $responseData; } else { //no valid answer received: request period is too big, etc. if (strpos($contentType, 'xml') === false) { echo 'Header returned: ' . $headerCode; echo $responseData; } else { //YOUR CODE HERE AFTER RECEIVING the xml with one of the codes from Instant Search Export Handbook $xml = $responseData; $xml = simplexml_load_string($xml); $response = array(); $i = 0; foreach ($xml->children() as $child) { $response[$i] = $child; $i++; } echo $xml->asXML(); } } //*********FUNCTIONS FOR HMAC********* function ArrayExpand($array) { $retval = ""; foreach ($array as $i => $value) { if (is_array($value)) { $retval .= ArrayExpand($value); } else { $size = strlen(StripSlashes($value)); $retval .= $size . StripSlashes($value); } } return $retval; } ``` {% endcode %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.2checkout.com/2checkout-apis/2checkout-apis/webhooks/api-message-services/instant-order-search-export-ise.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.