Introduction

The Hip eCommerce API provides a simple RESTful interface with lightweight JSON-formatted responses to use many of Hip eCommerce's websites features, including public Listings, Stores, and Sales (Orders), using API Keys to allow both read and write access to users' public and private data. This document provides information to developers on how to integrate with the Hip eCommerce API.

Accessing the API

The Hip eCommerce API is accessed via the /api directory within the primary domain of each of our marketplaces:

HipStamp: https://www.hipstamp.com/api
HipPostcard: https://www.hippostcard.com/api
HipComic: https://www.hipcomic.com/api

A sample unauthenticated request might look like:

GET https://www.hipstamp.com/api/listings/active?api_key={YOUR_API_KEY}

To retrieve recent active listings on HipStamp.

Important! Always ensure you are using the correct Base URL, including when testing here within our docs, as API Keys are not shared across different websites.

API requests must use HTTPS; HTTP requests will result in 400 Bad Request responses.

Authentication

The Hip eCommerce API requires an application key that is provided during app registration. The key identifies your application to the Hip eCommerce web service, and is used to track overall call usage. It's passed using the standard api_key parameter, or alternatively through the X-ApiKey header in your request.

New users register an application and receive a provisional API key upon signup. These keys have full access to resources in the Hip eCommerce API; however, they are restricted to allow authentication only for the user who registered the application.

Rate Limiting

Clients are allowed 10,000 requests per 24-hour period, with a limit of 10 queries per second, per API key.

If your application needs more than the allotted number of calls, Contact Us with a description of the application and an estimate on needed call usage. You might also want to investigate the use of caching to keep the number of calls to a minimum, and make your application more responsive.

Headers: Every API response bears rate limit headers, as described below:

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9650

These default rate limits are subject to change at any time, without notice.

API Requests

The Hip eCommerce API uses a RESTful calling style that works with standard HTTP calls. Any web programming language (PHP, Perl, Python, Java...) should be able to make and receive HTTP networking calls; consult the documentation for your language of choice.

Request URLs

In a RESTful API, each resource or collection of resources is identified by a unique URL, such as:

https://www.hipstamp.com/api/listings/:id

URL paths contain the unique IDs of resources. These are identified by a leading colon, as with :id above. Before making a call, you must substitute a valid ID value for these placeholders. ID parameters must appear in the URL and cannot be substituted for GET parameters. All ID parameters listed in the URL pattern must be present.

Output Formats

The Hip eCommerce API returns data in JSON format.

HTTP Methods

RESTful APIs use standard HTTP methods to denote actions against a resource:

GET: Reads a resource. Returns HTTP 200 on success.
POST: Creates a new resource. Returns HTTP 201 on success (or 200 if a resource was updated).
PUT: Updates a resource. Returns HTTP 200 on success.
DELETE: Deletes a resource. Returns HTTP 200 on success.

Because some toolkits lack support for PUT and DELETE (most notably JavaScript) you can use method overloading to fake an HTTP method. Use a GET or POST call and append the standard _method parameter:

https://www.hipstamp.com/api/listings/12345?_method=DELETE

Parameter Types

Many API methods take one or more parameters. The default way to provide these parameters is either as query parameters of the URL itself or as POST parameters. However, for POST and PUT requests, we do offer two additional ways in which you can supply parameters; through a JSON object or an XML object (with a dummy root node).

To provide a JSON object, or an XML object (with a dummy root node), you must set the Content-Type header in your request as follows, respectively:

Content-Type: application/json
Content-Type: application/xml

If you are using the default way to provide parameters (either as query parameters of the URL itself or as POST parameters), you may leave the Content-Type blank, or utilize either of the following:

Content-Type: text/plain
Content-Type: multipart/form-data

The documentation for each method references these standard types:

Param Type	Meaning
`string`	Any string. Max 255 characters, unless otherwise specified.
`int`	A whole number value.
`time`	A time in the format `YYYY-MM-DD HH:MM:SS` or any string accepted by PHP's `strtotime()` function. Note that all times are Eastern Standard / Daylight.
`float`	A number with or without a decimal point. May be represented in output as a string to avoid precision errors.
`boolean`	A logical true or false value. May be passed to API requests as a "1" or "0". In JSON output, "1" or "0" will be used.
`username`	A user's username (not the same as a Store name).
`enum (values)`	A predefined list of string values, for example "black" and "white". Any value not in the list may result in an error. Review the field description for additional information on acceptable values if values are not specified.
`array (type)`	A list of values, separated by two pipe characters \|\| Each value must be a valid instance of the type. (See Array notes below).
`json_array (type)`	A JSON array object. (See JSON Array Object notes below).
`url`	A string representation of a valid URL.
`currency`	A 3-letter ISO 4217 code.

Array Notes:
When providing parameters via the standard way of the URL itself, or as POST parameters, arrays are represented as strings, with values separated by two consecutive pipe characters (ASCII code 124). For example, when creating a new listing, here are values for the images parameter, expressed as an array:

https://www.example.com/12345.jpg||https://www.example.com/uploads/12357.jpg

As previously noted, for POST and PUT requests, you can optionally supply parameters through a JSON object, or an XML object (with a dummy root node). In these cases (and again with the appropriate Content-Type header set) you can represent array data as it would be represented within a JSON object or XML. For example:

Content-Type: application/json

images: [
      "https://www.example.com/uploads/12345.jpg",
      "https://www.example.com/uploads/12357.jpg"
]

Content-Type: application/xml

<images>
      https://www.example.com/uploads/12345.png
</images>
<images>
      https://www.example.com/uploads/12357.png
</images>

JSON Array Object Notes:
As the response format for the Hip eCommerce API is JSON data, there is no difference between a standard array object and a JSON array object in the response sent. However, there is a difference between an array and a json_array when it comes to sending a request to the Hip eCommerce API. When providing parameters via the standard way of the URL itself, or as POST parameters, an array can be expressed by separating values with two pipe characters ||. However, there are some fields, most notably postage, which are more complex and cannot be expressed in this way.

In these cases, you must use a JSON object to represent the value of the parameter. For example:

"postage": [
    {
        "price": "2.50",
        "price_addl": "0.50",
        "method": "First Class",
        "location_groups": [ "Domestic" ]
    },
    {
        "price": "4.50",
        "price_addl": "0.75",
        "method": "First Class",
        "location_groups": [ "Everywhere Else" ]
    }
]

This is true even when providing parameters via the standard way of the URL itself, or as POST parameters. However, if you submitting parameters via XML, you may supply an equivalent XML node instead, as shown in the following example:

Content-Type: application/xml

<postage>
    <location_groups>Domestic</location_groups>
    <method>First Class</method>
    <price>2.50</price>
    <price_addl>0.50</price_addl>
</postage>
<postage>
    <location_groups>Everywhere Else</location_groups>
    <method>First Class</method>
    <price>4.50</price>
    <price_addl>0.75</price_addl>
</postage>

Standard Parameters:
Here is a list of standard parameters that are accepted by many or all API methods:

Param	Type	Meaning
`api_key`	`string`	Your API key. Required for all calls (unless set in the X-ApiKey header).
`_method`	`string`	Used to specify a custom HTTP method for method overloading.
`limit`	`int`	Specifies the maximum number of records to return. Default is 25.
`page`	`int`	Skips the first ((N-1) * limit) records before returning results. Combine with limit for pagination. Default is 1.

JSON Data

Data is returned using JSON, a lightweight serialization language that is compatible with many different languages. JSON is also syntactically correct JavaScript code, which means that it can be parsed with JavaScript's own eval() function.

Standard Response Format

Each API response is wrapped in a standard structure that holds the results of the API call, plus metadata about the request:

{
    "count": integer,
    "type": "result type",
    "results": [
        { "result object" }
    ],
    "params": { "parameters" }
}

count specifies the total number of results available for this call, which may be more than the number of results returned in this request.
results is an array of results. For consistency's sake, it is always an array, even if only one result is expected.
params echoes the parameters that were passed in the request.
type specifies the type of the objects in the results array. (See the individual pages under "API Reference".)
notices is an array of notices. This will only be returned when there are notices. An example of a notice would be when creating or updating a Listing, if you specify a title which is longer than 80 characters, your Listing will be accepted, but the title will be truncated to 80 characters. This will be included as a notice.
errors is an array of errors. If an error occurs, the appropriate response headers will be set via HTTP status code. However, a detailed explanation of any errors will be included in the errors array. This will only be returned when there is an error, and in which case neither count, results, params, type or notices will be returned.

Associations

As noted above, individual pages under "API Reference" detail the types of objects which may be returned in results. Each page will detail the Field Names of the fields which are returned - which will generally be lowercase (unless otherwise noted). Objects may also contain Associations, which will be objects of another type attached to the main object. Pay special attention to the fact that the names of these attached objects will generally be uppercase. For example, take a look at this snippet of a Listing result, with a Bids object attached:

"currency": "GBP",
"quantity": "1",
"start_price": "5.00",
"Bids": [
      {
            "user_id": "109400",
            "amount": "35.00",
            "outbid": "0",
            "created_at": "2017-11-16 10:41:51"
      }
],

Pagination

The default records returned per call is 25, and the maximum number that can be returned is 100. We provide limit and page parameters to allow navigation through larger data sets. Responses include a count field, which specifies the total number of records available via pagination. For performance reasons, the combination of (limit * page) is limited to a maximum value of 50000; except when accessing Listings which belong to the current User, in which case it is limited to a maximum value of 1000000.

Here's an example of sequential requests to paginate through 200 recent active listings, 50 at a time:

https://www.hipstamp.com/api/listings/active?limit=50&page=1
https://www.hipstamp.com/api/listings/active?limit=50&page=2
https://www.hipstamp.com/api/listings/active?limit=50&page=3
https://www.hipstamp.com/api/listings/active?limit=50&page=4

Standard Response Codes

The Hip eCommerce API uses standard HTTP status codes to indicate success or failure of API calls. Here are some common codes:

HTTP Code	Message	Meaning
`200`	OK	Success!
`201`	Created	A new resource was successfully created.
`400`	Bad Request	You've made an error in your request.
`403`	Forbidden	The data you're trying to access is private.
`404`	Not Found	The requested resource could not be found.
`405`	Method Not Allowed	A request method is not supported for the requested resource.
`429`	Rate Limit Exceeded	You've exceeded the rate limits for your account.
`500`	Server Error	An internal error on our side.

Tip: What's the difference between a 404 Not Found and a 200 OK with empty results? If you're searching for a specific record, say listing #654864, and it doesn't exist, that's a 404 Not Found. However, if you're searching for a set of records and no listings match your search, that's a 200 OK. There's nothing wrong with your request, but it doesn't match anything, and your result set is empty.

This might seem a little arbitrary, but it makes practical sense: search engines typically don't display an error page if your search comes up empty. On the other hand, trying to access a URL that doesn't exist will turn up a standard 404 error page. Your application will probably have similar behavior.