"Get Orders" API

this article last updated: March 9, 2015

Due to inevitable changes that will be made to the shopping cart software over time, the cart's variable and database structure may change from time to time without advanced notice. We will attempt to keep the information in this article up-to-date, but Modular Merchant makes no guarantee as to the accuracy of the information provided in this article. Use this information at your own risk.

Modular Merchant Gold (and higher) account plans have access to a "Get Orders" APIs that allow a remotely-hosted website to search for orders and/or retrieve the details of a specified set of orders.

All requests to retrieve order data should be submitted to the "Get Orders" API URL, located in your online store. An example of the URL for this API would look something like this: http://www.mystore.com/api/get_orders.php

When searching for orders, the search criteria should be specified in the search_rule section of the XML request. See the Search Options section below for a list of all available search options.

tip

To learn more about the cart's APIs (how requests should be structured, a sample query using PHP, etc.) we recommend looking over the Introduction to APIs article.

Sample XML Request

The XML request below will match all orders that have an email address containing @modularmerchant.com. The results will start from the 3rd matched record and return 11 results.

<?xml version="1.0" encoding="utf-8"?>
<xmlrequest>
   <admin_sid>123</admin_sid>
   <admin_key>23a1c9ba51d691a74b2fd</admin_key>
   <api_key>9c1bc31e15423a1c9ba</api_key>
   <search_type>keyword</search_type>
   <start_result>3</start_result>
   <number_of_results>11</number_of_results>
   <any_vs_all>any</any_vs_all>
   <order_by>orders.id</order_by>
   <asc_vs_desc>ASC</asc_vs_desc>
   <search_rule>
       <search_field>orders.email</search_field>
       <compare_type>*LIKE*</compare_type>
       <search_string>@modularmerchant.com</search_string>
   </search_rule>
    ...The search_rule section is repeated for each rule to search by.
</xmlrequest>

urlencode the xml data

The data contained in each XML node must be urlencoded. For example, if you wanted the "compare_type" node to be ">" (greater than):

Wrong: <compare_type>></compare_type>

Correct: <compare_type>%3E</compare_type>

search options

The following options can be used in the submitted XML query to specify the options to search the store's order records by:

admin_sid: The SID number of the admin submitting the query.

admin_key: The personal API Key of the admin submitting the query. (Found on the Admin Account Editor page.)

api_key: The account-wide API Key. (Found on the System Settings page.)

search_type: The type of search to perform. Currently only "keyword" is supported.

start_result: The number of the result to start with. "3" would start with the third result.

number_of_results: The number of results to include in the XML response.

any_vs_all: Specifies whether the results must match "all" or "any" of the search rules.

order_by: The database field by which to order the search results. Example: "orders.id".

asc_vs_desc: Whether the results should be ordered in ascending ("ASC") or descending ("DESC") order.

SEARCH RULES
The search_rules section is repeated for each rule to match.

search_string
The content to match against. For example, to find all orders with a Modular Merchant email address, the recommended search string would be "@modularmerchant.com".

compare_type
How the search string will be compared to the search field. Options include:

1. *LIKE* (The database record must contain the search string.)

2. *NOT LIKE* (The database record must not contain the search string.)

3. = (The database record is equal to the search string.)

4. != (The database record is not equal to the search string.)

5. > (The database record is greater than the search string.)

6. < (The database record is less than the search string.)

7. LIKE* (The database record starts with the search string.)

8. *LIKE (The database record ends with the search string.)

search_field
The database field to apply the search against. Some common options include:

product_attr_X: Search against a product attribute. Replace "X" with the attribute's SID number.

order_field_X: Search against a checkout field. Replace "X" with the field's SID number.

orders.adjustment: The value of any adjustment applied to the order's total.

aff_commission.value: The value of any affiliate commission earned.

aff_tid.aff_id: The SID of any affiliate associated with the order.

aff_commission.tid: The SID of any affiliate Tracking ID associated with the order.

orders.bill_address_1: The first line of the order's billing address.

orders.bill_address_2: The second line of the order's billing address.

orders.bill_city: The order's billing city.

orders.bill_country: The two-character ISO code of the order's billing country.

orders.bill_first_name: The first name of the order's billing address.

orders.bill_last_name: The last name of the order's billing address.

orders.bill_state: The two-character ISO code of the order's billing state.

orders.bill_zip: The order's billing zip/postal code.

orders.cmr_ip: The IP address associated with the order.

orders.cid: The SID of the customer associated with the order.

orders.digdel_password: The order's Digital Delivery password.

orders.email: The order's Email Address.

orders.gw_value: The order's Gift Wrapping Total.

orders.memo: The order's customer-viewable Memo.

orders.create_date: The date the order was created. (MM-DD-YYYY format)

orders.id: The order's SID number.

note.content: The order's Admin-Only Notes

orders.processor: The order's Order Processor (S = system, A = admin, C = customer)

orders.tax_value: The value of the order's taxes.

order_total: The order's total value.

orders.auth_date: The date the order's payment was authorized. (MM-DD-YYYY format)

orders.pay_date: The date the order's payment was received. (MM-DD-YYYY format)

orders.gateway: The order's Payment Gateway.

orders.phone_ac: The order's Phone Area Code.

orders.phone: The order's Phone Number.

order_item.pid: The SID number(s) of the products in the order.

product_value: The value of the products in the order.

order_shipment.ship_date: The date the order's shipment(s) were shipped. (MM-DD-YYYY format)

order_shipment.ship_method_id: The SID number of the order's shipping methods(s)

order_shipment.status: The SID number of the order's shipment status.

orders.sai: The SID number of the order's shipping address.

orders.ship_address_1: The first line of the order's shipping address.

orders.ship_address_2: The second line of the order's shipping address.

orders.ship_city: The order's shipping city.

orders.ship_country: The two-character ISO code of the order's shipping country.

orders.ship_first_name: The first name of the order's shipping address.

orders.ship_last_name: The last name of the order's shipping address.

orders.ship_state: The two-character ISO code of the order's shipping state.

orders.ship_zip: The order's shipping zip/postal code.

Sample XML Response

The response below corresponds with the sample XML request above. The XML response contains the orders that match the search criteria.

The response_status node contains a flag indicating whether the query was successful or failed.
The data node contains the orders that match the search criteria. Each order will be encapsulated in an order tag.

<?xml version="1.0" encoding="utf-8"?>
<response>
   <response_status>success</response_status>
   <data>
       <order>
           <id>12345</id>
           <gw_value>0.00</gw_value>
           <adjustment>0.00</adjustment>
           <cid>1</cid>
           <email>example%40modularmerchant.com</email>
           <create_date>1310161712</create_date>
           <auth_date>1310161712</auth_date>
           <pay_date>1310161712</pay_date>
           <processor>C</processor>
           <sai>123</sai>
           <ship_first_name>Rogart</ship_first_name>
           <ship_last_name>Thibblestien</ship_last_name>
           <ship_address_1>000+Paved+Road</ship_address_1>
           <ship_address_2>Suite+000</ship_address_2>
           <ship_city>Anytown</ship_city>
           <ship_state>OR_US</ship_state>
           <ship_zip>12345</ship_zip>
           <ship_country>US</ship_country>
           <bill_first_name>Loraine</bill_first_name>
           <bill_last_name>Gershawitz</bill_last_name>
           <bill_address_1>000+Gravel+Road</bill_address_1>
           <bill_address_2>Apartment+000</bill_address_2>
           <bill_city>My+Town</bill_city>
           <bill_state>WA_US</bill_state>
           <bill_zip>54321</bill_zip>
           <bill_country>US</bill_country>
           <phone_ac>555</phone_ac>
           <phone>555-5555</phone>
           <cmr_ip>12.34.56.78</cmr_ip>
           <pay_method>Credit+Card</pay_method>
           <cc_pan_id>1234</cc_pan_id>
           <bid>856ad5b40f0ba344bd2a5b3d4f1e3511</bid>
           <gateway>manual</gateway>
           <digdel_password>123ABC</digdel_password>
           <wish_list_id>0</wish_list_id>
           <reward_points_earned>0</reward_points_earned>
           <reward_points_spent>0</reward_points_spent>
           <memo>Thank+you+for+your+order!</memo>
           <aff_id>123</aff_id>
           <aff_com_id>456</aff_com_id>
           <aff_tid>789</aff_tid>
           <aff_com_value>1.23</aff_com_value>
           <order_item_qty>1</order_item_qty>
           <order_item_price>12.22</order_item_price>
           <cogs>1.11</cogs>
           <msrp>3.33</msrp>
           <state_tax>0.11</state_tax>
           <country_tax>0.22</country_tax>
           <zip_tax>0.33</zip_tax>
           <total_tax>0.66</total_tax>
           <ship_fee_value>0.01</ship_fee_value>
           <prod_add_ship_value>0.02</prod_add_ship_value>
           <zone_fee_value>0.04</zone_fee_value>
           <total_shipping>0.07</total_shipping>
           <adjustment_value>0.00</adjustment_value>
           <order_total>999.99</order_total>
            <gateway_responses>
               <response>
                   <response_id>123</response_id>
                   <response_text>Approved</response_text>
                </response>
                ...response node is repeated for each gateway response.
            </gateway_responses>
           <shipment>
               <id>1</id>
               <order_id>12345</order_id>
               <zone_fee_value>0.04</zone_fee_value>
               <prod_add_ship_value>0.02</prod_add_ship_value>
               <ship_fee_value>0.01</ship_fee_value>
               <ship_method_id>123</ship_method_id>
               <ship_date>1310161712</ship_date>
               <status>1</status>
               <ship_method_name>Standard+Ground</ship_method_name>
               <ship_method_type>UPS</ship_method_type>
               <ship_method_code>123</ship_method_code>
               <shipping_exempt>0</shipping_exempt>
               <order_item>
                   <prod_id>456</prod_id>
                   <prod_name>Example+Product</prod_name>
                   <shipping_exempt>0</shipping_exempt>
                   <weight>3</weight>
                   <length>1</length>
                   <width>2</width>
                   <height>3</height>
                   <dropship_id>123</dropship_id>
                   <ship_solo>0</ship_solo>
                   <id>1</id>
                   <order_id>12345</order_id>
                   <qty>1</qty>
                   <price>2.22</price>
                   <create_date>1310161713</create_date>
                   <shipment_id>1</shipment_id>
                   <gift_wrap>0</gift_wrap>
                   <event_id>0</event_id>
                   <cogs>1.11</cogs>
                   <msrp>3.33</msrp>
                   <price_adj>0.00</price_adj>
               </order_item>
                ...order_item node is repeated for each item in the shipment.
           </shipment>
            ...shipment node is repeated for each shipment in the order.
            <checkout_fields>
               <checkout_field>
                   <checkout_field_data_sid>123</checkout_field_data_sid>
                   <checkout_field_sid>456</checkout_field_sid>
                   <content>Pizza</content>
                   <title>What+is+your+favorite+food?</title>
                </checkout_field>
                ...checkout_field node is repeated for each checkout field.
            </checkout_fields>
            <customer_fields>
               <customer_field>
                   <customer_field_data_sid>987</customer_field_data_sid>
                   <customer_field_sid>654</customer_field_sid>
                   <content>Vernon</content>
                   <title>What+is+your+middle+name?</title>
                </customer_field>
                ...customer_field node is repeated for each customer field.
            </customer_fields>
            <customer_attributes>
               <customer_attribute>
                   <customer_attribute_data_sid>888</customer_attribute_data_sid>
                   <customer_attribute_sid>777</customer_attribute_sid>
                   <content>YES</content>
                   <title>Member+of+Super+Saver+Club?</title>
                </customer_attribute>
                ...customer_attribute node is repeated for each customer attribute.
            </customer_attributes>
       </order>
        ...order node is repeated for each order returned.
   </data>
</response>

tip

The XML data returned by the API is "url encoded". To improve its legibility, be sure to apply urldecode() or a similar function to it.

reference

The PHP website includes some tutorials on how to turn XML data into an object that PHP can use.

nodes included in the order response xml

Below are some definitions of some of the commonly used nodes of the response XML.

ORDER NODE

id: The order's SID (System ID) number.

gw_value: The value, if any, of the order's Gift Wrapping fees.

adjustment: Any adjustment that has been applied to the order's price.

cid: SID number of the customer associated with the order.

create_date: Unix timestamp of the date the order record was created.

auth_date: Unix timestamp of the date the order's funds were authorized for capture.

pay_date: Unix timestamp of the date the order's funds were captured.

processor: The system that submitted the order. C = customer, A = admin, S = software

sai: SID of the shipping address associated with the order.

reward_points_earned: The number of Reward Points, if any, earned by the order.

reward_points_spent: The number of Reward Points, if any, redeemed when the order was placed.

aff_id: The SID numbers of any affiliates associated with the order.

aff_com_id: The SID number of any affiliate commissions associated with the order.

aff_tid: The SID number of any affiliate Tracking IDs associated with the order.

aff_com_value: The values of any affiliate commissions earned by the order.

order_item_qty: The total quantity of products associated with the order.

order_item_price: The total price of all products associated with the order.

cogs: The total Cost Of Goods Sold of all products associated with the order.

msrp: The total Manufacturer's Suggested Retail Price of all products associated with the order.

state_tax: The total state-level taxes associated with the order.

country_tax: The total country-level taxes associated with the order.

zip_tax: The total zip code-level taxes associated with the order.

total_tax: The total taxes associated with the order.

ship_fee_value: The total fees associated with the order's shipping methods.

prod_add_ship_value: The total product-level "additional shipping" fees associated with the products in the order.

zone_fee_value: The total zone fees associated with the order.

total_shipping: The total composite shipping fees, equal to Ship Fee + Product-level additional shipping fees + Zone Fees.

order_total: The order's total value.

GATEWAY RESPONSES NODE

response_id: The ID number of the gateway's response. Whenever possible, this number will correspond with the ID number for the response that is provided by the specific gateway.

response_text: The contents of the response that is returned by the payment gateway.

SHIPMENT NODE

id: SID of the shipment.

order_id: The SID of the order that the shipment corresponds to.

zone_fee_value: The total zone fees associated with the shipment.

prod_add_ship_value: The total product-level "additional shipping" fees associated with the products in the shipment.

ship_fee_value: The total fees associated with the shipment's shipping method.

ship_method_id: The SID of the shipment's shipping method.

ship_date: The Unix timestamp of the date the shipment was shipped.

status: SID of the shipment's "ship status".

ship_method_name: The name of the shipment's shipping method.

ship_method_type: The agent associated with the shipment (FedEx, UPS, U.S.P.S., etc.)

ship_method_code: The agent-assigned code for the shipping method.

shipping_exempt: Whether the shipment is shipping exempt. No if zero, otherwise yes.

ORDER ITEM NODE

order_item: SID of the order item.

prod_id: SID of the product.

prod_name: Name of the product.

shipping_exempt: Whether the product is shipping exempt. No if zero, otherwise yes.

dropship_id: SID of the dropshipper associated with the product.

ship_solo: Whether the product ships by itself. No if zero, otherwise yes.

order_id: SID number of the order associated with this item.

qty: Quantity of the product.

price: Price of the product.

create_date: Unix timestamp of the date the order item was created.

shipment_id: SID of the shipment the order item belongs to.

gift_wrap: Whether the item needs to be gift wrapped. No if zero, otherwise yes.

event_id: The SID, if any, of the Event associated with this item.

cogs: The Cost Of Goods Sold of the item.

msrp: The Manufacturer's Suggested Retail Price of the item.

price_adj: Any adjustment that was applied to the item's price.

CHECKOUT FIELDS NODE

checkout_field_data_sid: The ID number of the order_field_data database record that contains the checkout field data.

checkout_field_sid: The SID number of the Checkout Field. This SID number can also be found in the Search Checkout Fields section of the store's Administration Area.

content: The value that was provided by the customer in the storefront.

title: The title of the Checkout Field.

CUSTOMER FIELDS NODE

customer_field_data_sid: The ID number of the customer_field_data database record that contains the customer field data.

customer_field_sid: The SID number of the Customer Field. This SID number can also be found in the Search Customer Fields section of the store's Administration Area.

content: The value that was provided by the customer in the storefront.

title: The title of the Customer Field.

CUSTOMER ATTRIBUTES NODE

customer_attribute_data_sid: The ID number of the customer_attr_data database record that contains the customer attribute data.

customer_field_sid: The SID number of the Customer Attribute. This SID number can also be found in the Search Customer Attribute section of the store's Administration Area.

content: The value that was entered by a store Administrator.

title: The title of the Customer Field.

Follow @modularmerchant

Rank and add a comment to this article

Only logged in users may leave comments and rank articles. Log in to have your say!