# Merchant API v2 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. ## Rate Limiting 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. ## Versioning and Deprecation Policy 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. ## Pagination 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. ## Webhooks 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. ### Webhook Security 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**: ```ruby 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) end ``` ### Webhook Reliability Webhook 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. Version: 2.0.0 ## Servers Production API ``` https://app.hive.app/merchant_api/v2 ``` Staging API ``` https://staging.app.hive.app/merchant_api/v2 ``` ## Security ### BearerAuth A merchant-scoped API token used to authenticate all API requests. This token provides access to all sales channels owned by the merchant. Type: http Scheme: bearer Bearer Format: token ## Download OpenAPI description [Merchant API v2](https://hive-merchant-api.redocly.app/_bundle/Merchant%20API%20v2/mapi_v2_oas31.yaml) ## Inventory Operations related to inventory ### List inventory transactions - [GET /inventory/transactions](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/inventory/listinventorytransactions.md): Returns inventory transactions across all sales channels belonging to the authenticated merchant. See the Pagination section in the API overview above for details on how pagination works. ## InventoryTransferOrders Operations related to inventory transfer orders ### List inventory transfer orders - [GET /inventory_transfer_orders](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/inventorytransferorders/listinventorytransferorders.md): Returns all inventory transfer orders for the merchant. See the Pagination section in the API overview above for details on how pagination works. ### Create a new inventory transfer order - [POST /inventory_transfer_orders](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/inventorytransferorders/createinventorytransferorder.md): Creates a new inventory transfer order for the merchant. ### Get an inventory transfer order - [GET /inventory_transfer_orders/{id}](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/inventorytransferorders/getinventorytransferorder.md): Returns a specific inventory transfer order. ### Partially update an inventory transfer order - [PATCH /inventory_transfer_orders/{id}](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/inventorytransferorders/patchinventorytransferorder.md): Partially updates an existing inventory transfer order. Only the provided fields will be updated. ### Cancel an inventory transfer order - [PUT /inventory_transfer_orders/{id}/cancel](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/inventorytransferorders/cancelinventorytransferorder.md): Cancels an existing inventory transfer order. ### Inventory transfer order status updated webhook - [POST inventory_transfer_order.status_updated](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/inventorytransferorders/inventorytransferorderstatusupdatedwebhook.md) ### Inventory transfer order status updated webhook - [POST inventory_transfer_order.status_updated](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/webhooks/inventorytransferorderstatusupdatedwebhook.md) ## Webhooks Webhook event notifications ### Inventory transfer order status updated webhook - [POST inventory_transfer_order.status_updated](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/inventorytransferorders/inventorytransferorderstatusupdatedwebhook.md) ### Order status updated webhook - [POST order.status_updated](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/orders/orderstatusupdatedwebhook.md) ### Restocking shipment status updated webhook - [POST restocking_shipment.status_updated](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/restockingshipments/restockingshipmentstatusupdatedwebhook.md) ### Return status updated webhook - [POST return.status_updated](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/returns/returnstatusupdatedwebhook.md) ### Shipment status updated webhook - [POST shipment.status_updated](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/shipments/shipmentstatusupdatedwebhook.md) ### Shipment delivery status updated webhook - [POST shipment.delivery_status_updated](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/shipments/shipmentdeliverystatusupdatedwebhook.md) ### Order status updated webhook - [POST order.status_updated](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/webhooks/orderstatusupdatedwebhook.md) ### Shipment status updated webhook - [POST shipment.status_updated](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/webhooks/shipmentstatusupdatedwebhook.md) ### Shipment delivery status updated webhook - [POST shipment.delivery_status_updated](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/webhooks/shipmentdeliverystatusupdatedwebhook.md) ### Restocking shipment status updated webhook - [POST restocking_shipment.status_updated](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/webhooks/restockingshipmentstatusupdatedwebhook.md) ### Return status updated webhook - [POST return.status_updated](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/webhooks/returnstatusupdatedwebhook.md) ### Inventory transfer order status updated webhook - [POST inventory_transfer_order.status_updated](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/webhooks/inventorytransferorderstatusupdatedwebhook.md) ## Orders Operations related to orders ### List orders - [GET /orders](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/orders/listorders.md): Returns all orders across all sales channels belonging to the authenticated merchant. See the Pagination section in the API overview above for details on how pagination works. ### Create a new order - [POST /orders](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/orders/createorder.md): Creates a new order for a specific sales channel within the merchant's organization. ### Get an order - [GET /orders/{id}](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/orders/getorder.md): Returns a specific order. ### Partially update an order - [PATCH /orders/{id}](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/orders/patchorder.md): Partially updates an existing order. Only the provided fields will be updated. Note: The unique identifiers merchant_order_id and sales_channel_id cannot be updated and will be ignored if provided in the request body. ### Cancel an order - [PUT /orders/{id}/cancel](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/orders/cancelorder.md): Cancels an existing order. ### Get an order by merchant order ID and sales channel - [GET /orders/by_merchant_order_id](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/orders/getorderbymerchantid.md): Returns a specific order using the merchant's order ID and sales channel ID. ### Partially update an order by merchant order ID and sales channel - [PATCH /orders/by_merchant_order_id](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/orders/patchorderbymerchantid.md): Partially updates an order using the merchant's order ID and sales channel ID. Note: The unique identifiers merchant_order_id and sales_channel_id cannot be updated and will be ignored if provided in the request body. ### Order status updated webhook - [POST order.status_updated](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/orders/orderstatusupdatedwebhook.md) ### Order status updated webhook - [POST order.status_updated](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/webhooks/orderstatusupdatedwebhook.md) ## RestockingShipments Operations related to restocking shipments ### List restocking shipments - [GET /restocking_shipments](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/restockingshipments/listrestockingshipments.md): Returns all restocking shipments for the merchant. See the Pagination section in the API overview above for details on how pagination works. ### Create a restocking shipment - [POST /restocking_shipments](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/restockingshipments/createrestockingshipment.md): Creates a new restocking shipment for the merchant. ### Get a restocking shipment - [GET /restocking_shipments/{id}](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/restockingshipments/getrestockingshipment.md): Returns a specific restocking shipment. ### Update a restocking shipment (replace only, allowed if status is "shipped" or "created") - [PUT /restocking_shipments/{id}](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/restockingshipments/updaterestockingshipment.md): Updates an existing restocking shipment. Only allowed if the shipment status is "shipped" or "created". This operation replaces the entire resource. ### Cancel a restocking shipment - [PUT /restocking_shipments/{id}/cancel](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/restockingshipments/cancelrestockingshipment.md): Cancels an existing restocking shipment. ### Restocking shipment status updated webhook - [POST restocking_shipment.status_updated](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/restockingshipments/restockingshipmentstatusupdatedwebhook.md) ### Restocking shipment status updated webhook - [POST restocking_shipment.status_updated](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/webhooks/restockingshipmentstatusupdatedwebhook.md) ## Returns Operations related to returns ### List returns - [GET /returns](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/returns/listreturns.md): Returns all returns across all sales channels belonging to the authenticated merchant. See the Pagination section in the API overview above for details on how pagination works. ### Get a return - [GET /returns/{id}](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/returns/getreturn.md): Returns a specific return. ### Return status updated webhook - [POST return.status_updated](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/returns/returnstatusupdatedwebhook.md) ### Return status updated webhook - [POST return.status_updated](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/webhooks/returnstatusupdatedwebhook.md) ## SKUs Operations related to Stock Keeping Units (SKUs) ### List SKUs - [GET /skus](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/skus/listskus.md): Returns all SKUs belonging to the authenticated merchant. See the Pagination section in the API overview above for details on how pagination works. ### Create a new SKU - [POST /skus](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/skus/createsku.md): Creates a new SKU for the merchant. SKUs must have a unique SKU code. New SKUs are marked as "verified" and fulfilled_by "hive". ### Delete a SKU - [DELETE /skus/{id}](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/skus/deletesku.md): Deletes an existing SKU. ### Get a SKU by ID - [GET /skus/{id}](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/skus/getsku.md): Returns a specific SKU by its ID. ### Partially update a SKU - [PATCH /skus/{id}](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/skus/patchsku.md): Partially updates an existing SKU. Only the provided fields will be updated. ### Get a SKU by merchant SKU code - [GET /skus/by_sku_code](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/skus/getskubycode.md): Returns a specific SKU using the merchant's SKU code. ### Partially update a SKU by merchant SKU code - [PATCH /skus/by_sku_code](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/skus/patchskubycode.md): Partially updates a SKU using the merchant's SKU code. ### Delete a SKU by merchant SKU code - [DELETE /skus/by_sku_code](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/skus/deleteskubycode.md): Deletes a SKU using the merchant's SKU code. ## SalesChannels Operations related to sales channels ### List sales channels - [GET /sales_channels](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/saleschannels/listsaleschannels.md): Returns all sales channels available to the merchant. See the Pagination section in the API overview above for details on how pagination works. ## Shipments Operations related to shipments ### List shipments - [GET /shipments](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/shipments/listshipments.md): Returns all shipments across all sales channels belonging to the authenticated merchant. See the Pagination section in the API overview above for details on how pagination works. ### Shipment status updated webhook - [POST shipment.status_updated](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/shipments/shipmentstatusupdatedwebhook.md) ### Shipment delivery status updated webhook - [POST shipment.delivery_status_updated](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/shipments/shipmentdeliverystatusupdatedwebhook.md) ### Shipment status updated webhook - [POST shipment.status_updated](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/webhooks/shipmentstatusupdatedwebhook.md) ### Shipment delivery status updated webhook - [POST shipment.delivery_status_updated](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/webhooks/shipmentdeliverystatusupdatedwebhook.md) ## Warehouses Operations related to warehouses ### List warehouses - [GET /warehouses](https://hive-merchant-api.redocly.app/merchant-api-v2/mapi_v2_oas31/warehouses/listwarehouses.md): Returns all warehouses available to the merchant. See the Pagination section in the API overview above for details on how pagination works.