Merchant API v2 (2.0.0)
The Merchant API v2 provides programmatic access to merchant data across all their sales channels.
This version shifts from sales channel-scoped access to merchant-scoped access, allowing access to data across all sales channels owned by a single merchant.
The access tokens remain the same as in v1, but now they provide access to all sales channels.
Every request must be authenticated with an API access token, sent as a bearer token in the Authorization header:
Authorization: Bearer your_api_tokenGenerate tokens yourself in the Hive app: go to Settings → Sales channels, click Set up on the Hive API card, and click Generate new key under API keys. If you have no Hive API sales channel yet, Set up asks you to create one first. You can reveal and copy a key there at any time, and deactivate it to revoke it immediately. A merchant can have up to 5 active keys.
Keys can be generated by admins of merchants on Hive Pro+. If the Hive API card shows Request instead of Set up, click it and our team will get in touch. Keys from the Hive app work on production, https://app.hive.app. To test against staging, https://staging.app.hive.app, first ask your account manager for a staging account; Hive provides its login and a staging token.
All endpoints are rate limited to 100 requests per minute per merchant. The following headers are included in every response:
X-Rate-Limit-Used: The number of requests used in the current minute.X-Rate-Limit-Max: The maximum number of requests allowed per minute (100). If the limit is exceeded, a 429 Too Many Requests response is returned.
v1 of the Merchant API will remain available as long as clients use it, but new features and improvements will only be added to v2. We recommend all new integrations use v2.
All list endpoints use cursor-based pagination. The pagination.next_page_url field in the response indicates the next page. If null, there are no more results. Use the limit query parameter to control page size. See each endpoint's response schema for details.
Hive sends webhook notifications to inform you about important events in your merchant account. Configure webhook endpoints in your merchant dashboard. See the webhooks section below for available webhook events and their payloads.
Hive signs all webhook requests with an x-hive-signature header to prevent malicious actors from sending invalid requests. This header contains a hex-encoded HMAC-SHA256 digest of the request body, using your API token as the key. Requests without this header or with invalid signatures should be ignored.
Ruby signature validation example:
def request_valid?(req)
return false if !req.post?
request_sig = req.get_header("x-hive-signature")
expected_sig = OpenSSL::HMAC.hexdigest("sha256", ENV["API_TOKEN"], req.body)
Rack::Utils.secure_compare(request_sig, expected_sig)
endWebhook URLs should be idempotent as Hive cannot guarantee the order of calls or retry attempts for the same event. What this means in practice, is that you should check the timestamp of the object in the payload. Ignore payloads with a timestamp older than the last update you saved. Only process the webhook if the updated timestamp is newer than the one you have on file.