General

Authentication

All API requests need to be authenticated. To do this, you need to always send the HTTP header Authorization with your API key as a bearer token:

Authorization: Bearer your_api_key

Rate limits

To protect our servers from getting overloaded and avoid misuse, we enforce a rate limit of 100 requests per minute. You shouldn't need to poll frequently for status updates as you can get real-time updates via Webhooks. In case you have a valid use case for a higher rate limit, please contact your account manager.

The API responds with the following headers to indicate the number of requests used and the maximum available:

X-Rate-Limit-Used: 42
X-Rate-Limit-Max: 100

Any requests above the limit will be denied with a 429 response code (too many requests). In that case, the response also includes an extra header which shows how many seconds you need to wait before sending a new request:

Retry-After: 3.2

Errors

When a request is unsuccessful, you will get an HTTP status code of 4xx (for client errors) or 5xx (for server errors). The body then will always contain an errors property which contains an array of human-readable errors.

Common errors

If your API key is missing, or wrong, you'd get a 401 Unauthorized with this JSON response:

{
  "success": false,
  "errors": [
    "authentication required"
  ]
}

Another example, when the request is malformed, you'd get a 400 Bad request:

{
  "success": false,
  "errors": [
    "bad request"
  ]
}

Finally, if the data is not valid, you'd get a 422 Unprocessable Entity:

{
  "success": false,
  "errors": [
    "Name can't be blank",
    "Merchant sku can't be blank"
  ]
}

Successful responses

When an API request is successful, you will get an HTTP status code of 2xx. The response body will either be a single object or a collection of objects.

Single object

When you create or update an object, you will get the final state of the object in the response:

{
    "id": 34,
    "merchant_sku_id": "HIVE_TSH_BLK_M",
    "name": "Hive T-Shirt (Black - M)",
    "created_at": "2022-08-10T17:53:04.438+02:00",
    "cost_in_cents": null,
    "country_code_of_origin": null,
    "hs_code": null,
    "weight_in_kg": 0.3,
    "inventory": {
        "stocked": 10000,
        "reserved": 0,
        "total": 10000
    }
}

Collection of objects

When you get a collection of objects in the response, the response is an object with a data property and a pagination property. The actual collection of object is in the data property:

{
  "data": [
    {
      "id": 9,
      "merchant_sku_id": "2218061549136",
      "name": "Morph II",
      "created_at": "2022-08-10T17:53:04.822+02:00",
      "cost_in_cents": null,
      "country_code_of_origin": null,
      "hs_code": null,
      "weight_in_kg": 45.37,
      "inventory": {
        "stocked": 10000,
        "reserved": 0,
        "total": 10000
      }
    },
    {
      "id": 4,
      "merchant_sku_id": "4976808834423",
      "name": "Mr Moonstone",
      "created_at": "2022-08-10T17:53:04.507+02:00",
      "cost_in_cents": null,
      "country_code_of_origin": null,
      "hs_code": null,
      "weight_in_kg": 24.92,
      "inventory": {
        "stocked": 10000,
        "reserved": 0,
        "total": 10000
      }
    }
  ],
  "pagination": {
    "current_page": 1,
    "item_count": 2,
    "page_count": 1,
    "items_per_page": 20
  }
}

Pagination

In order to access all the objects of the collection, you need to send multiple requests to an endpoint. This works by adding the query string parameter page to the URL (e.g. https://app.hive.app/merchant_api/v1/skus?page=2)

The pagination.page_count property of the response, returns how many pages are available. If no page parameter is provided, it defaults to 1 (that is, the first page of results).