Search

How to search using the MerchantOS API

When doing GET requests from controls you can provide search parameters. For example if you are reading items from /API/Account/{account id}/Item you can provide search parameters like ?upc=12345678901. This will find items with a matching UPC. The parameters below are general and can be used on any search (unless otherwise noted).

archived

• archived=[0|1]
• Use: When set to 1, includes archived records in the result set.
• Allowed Values: 1,0

limit

• limit=[0|1]
• Use: The maximum number of records to return.
• Allowed Values: Any Integer >= 0
• Default: 100
• Tip: It's a good idea to always include a limit. It will speed up your queries and you won't get surprised by our automatic 100 limit.

load_relations

• load_relations=\["relation_name","relation_name",...\]
• Use: If set will load the requested relations on the requested object
• Allowed Values: A JSON encoded array of any valid relation names. See the API Documentation for relation names.
• Tip: By default no relations are loaded. You must pass a JSON encoded array of all of the relations that you want loaded. To load all relations pass the string value "all".

offset

• offset=[integer > 0]
• Use: Offset to start the the list of results at. With limit and offset you can page through results.
• Allowed Values: Any Integer > 0

orderby

• orderby=[field_name]
• Use: A field to order the result set by. You can specify any of the fields listed below. The default direction is ascending.
• Allowed Values: Any valid field in the parent data model or it's first level relations*.

orderby_desc

• orderby_desc=[1,0]
• Use: Make the orderby use a descending order instead of ascending.
• Allowed Values: 1,0

version

• version=[1,2]
• Use: Specify the API version for the request. If a HTTP Accept header is set that specifies the version that takes precedence over this search parameter.
• Allowed Values: 1,2

General Field Search Parameters

You can search on any field in the parent data model or it's first level relations*.

Search Operators

You can use a variety of operators to make your searches more powerful. Here's a list of supported operators:

• =, default, no operator needs to be specified.
• >, url encoded: %3E
• >=, url encoded: %3E%3D
• <, url encoded: %3C
• <=, url encoded: %3C%3D
• !=, url encoded: !%3D
• ~ , a 'like' operator, used for string comparisons. You can use the % character as a wild card (% url encoded is %25).
• !~ , a 'not like' operator, used for string comparisons. You can use the % character as a wild card (% url encoded is %25).
• "IN", allows you to search for multiple IDs at once, the IDs list can be commas separated or a JSON encoded array. (Example: itemID=IN,[1,2,3])
• ><, url encoded: %3E%3C - The BETWEEN operator. Search values that are within a range. (Example: itemID=><,1,10 would return all itemIDs greater than or equal to 1 and less than or equal to 10)
• or, an 'or' operator, used to search for several alternate values. Or queries are formatted like this or=description%3Dfoo|description%3Dbar (this query will search for a description of foo or bar). All equals in the 'or' query must be percent encoded or the query will fail. You can use all of the above search operators in your 'or' query (or=description%3D~,foo|description%3D~,bar this will search for a description like foo or like bar).

The default operator is '='. To specify a different operator from the list above you embed the operator in the value of the query parameter like this in the format [parameter name]=[operator],[search value]. The operator and following comma must be url encoded. An example would be "amount=>=,5", url encoded this would be: "amount=%3E%3D%2C5". Here's a quick url encoder if you need help encoding things: [URL Decoder / Encoder].

<parent>
  <field></field>
  <child1>
    <field></field>
  </child1>
  <child2>
    <grandchild1>
      <field></field>
    </grandchild1>
  </child2>
<parent>

Examples

Get second set of 20 item records.

curl -v -X GET -u 'user:pass' -H 'Content-Type: text/xml' https://api.merchantos.com/API/Account/{accountID}/Item?limit=20\&offset=20

Date Filtered Search. Show transactions only on 2012-03-16

curl -v -X GET -u 'user:pass' -H 'Content-Type: text/xml' https://api.merchantos.com/API/Account/{account ID}/Sale?timeStamp=%3E%3C,2012-03-15,2012-03-17