Interspire Product Knowledge Base

What is an API?

An API (or application programming interface) is a way to programatically extract data from your store in a common XML file format. You can then manipulate the XML using a scripting language (such as PHP) to perform a task such as reconciling orders into your accounting software, copying your customers into a third party CRM, etc.

In this article the Interspire Shopping Cart API will be explained, along with examples where appropriate. Please note that this article assumes you are familiar with PHP and XML, and you should only enable and use the API if you are a confident programmer.

Introducing the Interspire Shopping Cart API

Interspire Shopping Cart includes a basic API that allows you to pull orders, customers and products from your store. The includes/classes/api/example.php file shows how the API can be used. You can retrieve items by passing search criteria as part of your XML request to the API. For example, to get a list of customers from America whose email address contained "@gmail.com", you would pass the following details in your XML API request:

...
<details>
     <searchQuery>gmail.com</searchQuery>
     <country>226</country>
</details>
...

The country is passed through as a number, which is the country ID as found in the MySQL countries table. To retrieve a list of products whose title contains the word "laserjet", you would use pass the following XML to the API:

<xmlrequest>
    <username>john</username>
    <usertoken>9baa79a5871a2bdaac7b437a5b7275a8daff88d9</usertoken>
    <requesttype>products</requesttype>
    <requestmethod>GetProducts</requestmethod>
    <details>
         <searchQuery>laserjet</searchQuery>
    </details>
</xmlrequest>

There are 4 parameters in the XML that are required for every call to the API:

1. username: Your Interspire Shopping Cart account username. This account will need to have access to the XML API, which you can enable by editing the account and ticking the "Yes, allow this user to use the XML API" checkbox
2. usertoken: Available when you tick the "Yes, allow this user to use the XML API" box from the users page
3. requesttype: This will be either orders, products, or customers
4. requestmethod: The specific API request you want to call. See the example.php file in the includes/classes/api folder for the list of request methods currently available

As a quick example, here's the XML you would send to the API to see a list of new orders placed in the last 7 days:

<xmlrequest>
    <username>john</username>
    <usertoken>9baa79a5871a2bdaac7b437a5b7275a8daff88d9</usertoken>
    <requesttype>orders</requesttype>
    <requestmethod>GetOrders</requestmethod>
    <details>
        <dateRange>week</dateRange>
    </details>
</xmlrequest>

Combining Filters Using the API

As well as searching basic order/product/customer details, you can also filter the items shown based on other factors, such as date or cost. The fields you can pass in are identical to the fields on the Advanced Search page for orders, products and customers from the Interspire Shopping Cart control panel. You simply get the ID of the field and pass it in with a value.

To find which fields you can use to filter orders, for example, double click the Orders tab in the control panel and then click the Advanced Search link. View the HTML source code of the page or use a tool such as FireBug to see the ID attribute of the fields on the page. For example, the orderFrom and orderTo fields let me specify a range of order ID's that I would like the XML API to return. To implement this I would pass the following XML to the API:

<xmlrequest>
        <username>john</username>
        <usertoken>9baa79a5871a2bdaac7b437a5b7275a8daff88d9</usertoken>
        <requesttype>orders</requesttype>
        <requestmethod>GetOrders</requestmethod>
        <details>
            <orderFrom>1</orderFrom>
            <orderTo>100</orderTo>
        </details>
</xmlrequest>

The API would then return a list of orders in XML format whose order ID field contained a value between 1 and 100 (inclusive).

Here's another example that shows how to get all orders placed in the last 7 days where the total amount was over $200 and any field for the order (such as billing name, shipping name, etc) contained the search phrase "seinfield":

<xmlrequest>
    <username>john</username>
    <usertoken>9baa79a5871a2bdaac7b437a5b7275a8daff88d9</usertoken>
    <requesttype>orders</requesttype>
    <requestmethod>GetOrders</requestmethod>
    <details>
        <dateRange>week</dateRange>
        <totalFrom>200</totalFrom>
        <searchQuery>seinfield</searchQuery>
    </details>
</xmlrequest>

The items are returned as XML, which can then be processed as required. As mentioned earlier, the includes/classes/api/example.php file contains examples of using the API to fetch orders, products and customers, so it's a good idea to start with one of the example API calls and customize it as required.