{"templateId":"api_docs","sharedDataIds":{"apiDocsStore":"api-docs-Merchant API v2/mapi_v2_oas31.yaml","sidebar":"sidebar-sidebars.yaml"},"props":{"definitionId":"Merchant API v2/mapi_v2_oas31.yaml","settings":{"baseUrlPath":"/merchant-api-v2/mapi_v2_oas31"},"disableAutoScroll":true,"seo":{"title":"Merchant API v2","llmstxt":{"hide":true}},"dynamicMarkdocComponents":[],"metadata":{"type":"openapi","title":"Merchant API v2","version":"2.0.0","description":"The Merchant API v2 provides programmatic access to merchant data\nacross all their sales channels.\n\nThis version shifts from sales channel-scoped access to merchant-scoped access,\nallowing access to data across all sales channels owned by a single merchant.\n\nThe access tokens remain the same as in v1, but now they provide access to all sales channels.\n\n## Access tokens\nEvery request must be authenticated with an API access token, sent as a bearer token in the `Authorization` header:\n\n```\nAuthorization: Bearer your_api_token\n```\n\nGenerate 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.\n\nKeys 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.\n\n## Rate Limiting\nAll endpoints are rate limited to 100 requests per minute per merchant. The following headers are included in every response:\n- `X-Rate-Limit-Used`: The number of requests used in the current minute.\n- `X-Rate-Limit-Max`: The maximum number of requests allowed per minute (100).\nIf the limit is exceeded, a 429 Too Many Requests response is returned.\n\n## Versioning and Deprecation Policy\nv1 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.\n\n## Pagination\nAll 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.\n\n## Webhooks\nHive 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.\n\n### Webhook Security\nHive signs all webhook requests with an `x-hive-signature` header to prevent\nmalicious actors from sending invalid requests. This header contains a hex-encoded HMAC-SHA256\ndigest of the request body, using your API token as the key. Requests without this header or\nwith invalid signatures should be ignored.\n\n**Ruby signature validation example**:\n```ruby\ndef request_valid?(req)\n  return false if !req.post?\n  request_sig = req.get_header(\"x-hive-signature\")\n  expected_sig = OpenSSL::HMAC.hexdigest(\"sha256\", ENV[\"API_TOKEN\"], req.body)\n  Rack::Utils.secure_compare(request_sig, expected_sig)\nend\n```\n\n### Webhook Reliability\nWebhook URLs should be idempotent as Hive cannot guarantee the order of calls\nor retry attempts for the same event. What this means in practice, is that you should check the\ntimestamp of the object in the payload. Ignore payloads with a timestamp older than the last\nupdate you saved. Only process the webhook if the updated timestamp is newer than the one you\nhave on file.\n"},"compilationErrors":[],"markdown":{"partials":{},"variables":{"rbac":{"teams":["anonymous"]},"user":{},"remoteAddr":{"hostname":"developers.hive.app","port":4000,"ipAddress":"216.73.217.122"},"lang":"default_locale","env":{"PUBLIC_REDOCLY_BRANCH_NAME":"main"}}},"pagePropGetterError":{"message":"","name":""}},"slug":"/merchant-api-v2/mapi_v2_oas31","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}