Basics of the MerchantOS API

Learn the basics of the MerchantOS RESTful API and how you can get started developing your application.

Read Getting an API Key to obtain your API Key.

The MerchantOS API (Application Programming Interface) allows you to access the MerchantOS system in a programatic manner. That means you can hire a developer (or do it yourself if you know how to write some code) to access almost everything within your MerchantOS account. This allows for 3rd party application integrations. For example you could create an application that syncs your MerchantOS data with your Ecommerce system.

Some basic facts of the MerchantOS:

1. RESTful API.
2. Supports XML or JSON
3. Basic HTTP authentication with a username/password or an API Key (read Getting Started to generate an API Key)

Let's begin with an example of a request to the API.

https://imademo:thisismypass@api.merchantos.com/API/Controls

News And Updates

Important updates to the API will be announced here https://groups.google.com/forum/#!forum/merchantos-api-developers/. If you are a developer, you should subscribe or check in regularly to this list to be sure that future changes will not impact your integration.

Finding Your Account ID

Once you have a valid API key you can find your Account ID for making further requsts by accessing the following url:

https://api.merchantos.com/API/Account

Controls / End Points / Objects

Each API key has it's own set of Controls that it is authorized to access. Live documentation can be generated by these controls by using the .help extension. The URI /API/APIHelp.help gives access to all the individual Control help. For your convenience you can access the MerchantOS Demo account API Help using the link below:

https://merchantos.com/API/APIHelp.help

Reference

• Defined Values - Lists pre-defined values and constants.
• Definitions and Conventions - Defines attributes and other information about our API format.

Sample Code

You can find sample code for the MerchantOS API at our GitHub account: https://github.com/merchantos/api_samples

API Throttling

Your account is limited to ten requests per minute. To work within these limitations, your code should be prepared to receive an error 503 response. When this response is received, sleep your script for about 60 seconds then retry the last request before proceeding. Please use this method versus a time delay between each request. A time delay will cause your script to have errors or run more slowly than it needs to if throttling limits change. Furthermore, if another script is making API calls to the same account the API throttling limit could be reached sooner rendering a script with a time delay an unexpected error.

If you are having problems working within the ten requests per minute limitation, email support a short description of the requests you are making. We will try to help you get the same data with fewer requests.

Using cURL To Test

Using cURL we can do a test call in a more appropriate manner.

curl -v -u 'imademo:thisismypass' -G https://api.merchantos.com/API/Controls

That should give you something like this:

<?xml version="1.0"?>
<Controls>
  <Control>
    <Name>Account.CreditAccount</Name>
    <ExampleXML>/API/Account/1/CreditAccount.example</ExampleXML>
    <ActionsAllowed>
      <create>false</create>
      <readSingle>true</readSingle>
      <readMultiple>true</readMultiple>
      <update>false</update>
      <delete>false</delete>
    </ActionsAllowed>
    <PrivilegesNeeded>
      <customers>true</customers>
    </PrivilegesNeeded>
  </Control>
  <Control>
    <Name>Account.Customer</Name>
    <ExampleXML>/API/Account/1/Customer.example</ExampleXML>
    <ActionsAllowed>
      <create>false</create>
      <readSingle>true</readSingle>
      <readMultiple>true</readMultiple>
      <update>false</update>
      <delete>false</delete>
    </ActionsAllowed>
    <PrivilegesNeeded>
      <customers>true</customers>
    </PrivilegesNeeded>
  </Control>
  <Control>
    <Name>Account.Item</Name>
    <ExampleXML>/API/Account/1/Item.example</ExampleXML>
    <ActionsAllowed>
      <create>false</create>
      <readSingle>true</readSingle>
      <readMultiple>true</readMultiple>
      <update>false</update>
      <delete>false</delete>
    </ActionsAllowed>
    <PrivilegesNeeded>
      <inventory>true</inventory>
    </PrivilegesNeeded>
  </Control>