1 of 13

Hive Merchant API

Introduction

This is the documentation for the API which allows merchants to integrate their systems with Hive. Our API is used to integrate stores or ERP systems for which we do not yet have a native integration.

You can POST SKUs and orders, as well as retrieve fulfillment and delivery statuses of them. You can also use the Hive API to interact with other features of our WMS software, such as restocking shipments, returns and SKUs.

The API currently doesn't give access to all the data and features of the Hive app. That is, if you have multiple integrations, you cannot view or edit data from those integrations (e.g. orders).

If your platform of choice is listed in you don't need to use this API.

Want to jump right in?

Feeling like an eager beaver? Jump in to the quick start docs and get making your first request:

Want to deep dive?

Dive a little deeper and start exploring our API reference to get an idea of everything that's possible with the API:

Quick Start

Get your API key

Your API requests are authenticated using API keys. Any request that doesn't include an API key will return an error.

You can ask your account manager to create an API key for you.

The production domain for the HIVE API is https://app.hive.app/, the staging domain is https://staging.app.hive.app/

Install a REST client

The API uses JSON extensively. It only accepts requests where the body is valid JSON (so you need to set the header content-type: application/json in your requests). It's easier to interact with it using a REST client. Some options are:

for VS code

Changelog

List of API changes by date

2025-07-04

Document limit query parameter for pagination

2025-07-02

Fix expiry_date type in the shipping example payload (it's a date, not datetime)

2025-06-18

Practical advice for out-of-order webhook handling

2025-05-15

Add dangerous_good, h_codes, hazardous_good and un_names to Sku responses

2025-03-27

Clarification on merchant_item_idbeing nullfor shipment items added later as add-ons (i.e. not part of the order line items)

2024-08-08

Add merchant_item_id property to items in GET /shipments response

2024-06-26

Add items to GET /shipments response

2024-06-24

Add details about rate limit

2024-06-21

Edit introduction to clarify data scope of the API vs Hive app

2023-11-22

Document pagination parameter for collections

2023-09-18

Add optional include parameter to the GET /orders/{id} endpoint to retrieve the SKU batches included in the order

2023-08-01

Add DELETE /skus/{id} endpoint
Add status property to responses in SKUs endpoints

2023-07-21

Add optional include parameter to the GET /orders endpoint to retrieve the SKU batches included in the orders

2023-06-01

Add GET /returns endpoint
Add GET /returns/{id} endpoint

2023-05-30

Add barcode to the resource.

2023-05-29

Add production and staging domains in the page.

2023-05-18

Add batch inventory information to the resource.

2023-05-03

Change quantity to announced_quantity to restocking shipment item in the restocking shipment's response
Add arrived_quantity damaged_quantity missing_quantity to restocking shipment item in the restocking shipment's response

2023-04-26

Add POST /skus/bulk_upsert endpoint

2023-04-19

Add fulfilled_by property to responses in SKUs endpoints

2023-04-18

Add batch_tracking_enabled property in SKUs endpoints' responses and accept it in POST/PATCH
Add /restocking_shipments endpoints

2023-04-14

Add inventory_batches property to responses in SKUs endpoints

2023-04-11

Add currency property in Orders endpoints' responses and accept it in POST/PATCH

Reference

API Reference

Dive into the specifics of each API endpoint by checking out our complete documentation.

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

Shipments

The Shipment resource

Property

Type

Description

created_at

ISO8601 datetime

When the shipment was created

The ShipmentItem resource

Property

Type

Description

The ShipmentItemBatch resource

Property

Type

Description

The ShipmentItemSerialNumber resource

Property

Type

Description

The ShipmentItemSku resource

Property

Type

Description

List all shipments

Lists all shipments of an order

GET https://app.hive.app/merchant_api/v1/shipments

Returns shipments ordered by descending creation time.

Query Parameters

Name

Type

Description

Warehouses

The Warehouse resource

Property

Type

Description

Returns

The Return resource

Property

Type

Description

carrier

String

Carrier name

The ReturnItem resource

Property

Type

Description

The ReturnLineItem resource

Property

Type

Description

The ReturnSku resource

Property

Type

Description

The ReturnOrder resource

Property

Type

Description

The ReturnPhoto resource

Property

Type

Description

The ReturnLineItemPhoto resource

Property

Type

Description

List all returns

Lists all order returns

GET https://app.hive.app/merchant_api/v1/returns

Returns paginated order returns ordered by descending creation time.

Query Parameters

Name

Type

Description

Get one return

Get one specific order return

GET https://app.hive.app/merchant_api/v1/returns/{id}

Returns specific order return belonging to the merchant and with matching Hive ID

Path Parameters

Name

Type

Description

Webhooks

Webhooks allow merchants to be notified of significant events. For example, when the delivery status of a shipment changes. When an webhook-supporting event happens, an HTTP POST request will be sent to the URL of your choice.

To set up webhooks, ask your account manager. You need to provide the URL which handles the webhooks.

The following table shows the supported events and the type of payload which will be sent in the request:

Event type

Description

Payload

delivery_status_updated

The provided webhook URLs should be idempotent. We cannot guarantee the order of the calls neither the retries attempts for the same call.

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.

Security

Hive signs all webhook requests to prevent malicious actors from sending invalid requests. Requests without the x-hive-signature HTTP request should be ignored. If the header is present, it should match the hex-encoded HMAC-SHA256 digest of the request body, with your API token as the key.

Here's an example of how one would calculate the HMAC-SHA256 digest:

Changelog

List of API changes by date

2025-07-04

Document limit query parameter for pagination

2025-07-02

Fix expiry_date type in the shipping example payload (it's a date, not datetime)

2025-06-18

Practical advice for out-of-order webhook handling

2025-05-15

Add dangerous_good, h_codes, hazardous_good and un_names to Sku responses

2025-03-27

Clarification on merchant_item_idbeing nullfor shipment items added later as add-ons (i.e. not part of the order line items)

2024-08-08

Add merchant_item_id property to items in GET /shipments response

2024-06-26

Add items to GET /shipments response

2024-06-24

Add details about rate limit

2024-06-21

Edit introduction to clarify data scope of the API vs Hive app

2023-11-22

Document pagination parameter for collections

2023-09-18

Add optional include parameter to the GET /orders/{id} endpoint to retrieve the SKU batches included in the order

2023-08-01

Add DELETE /skus/{id} endpoint
Add status property to responses in SKUs endpoints

2023-07-21

Add optional include parameter to the GET /orders endpoint to retrieve the SKU batches included in the orders

2023-06-01

Add GET /returns endpoint
Add GET /returns/{id} endpoint

2023-05-30

Add barcode to the resource.

2023-05-29

Add production and staging domains in the page.

2023-05-18

Add batch inventory information to the resource.

2023-05-03

Change quantity to announced_quantity to restocking shipment item in the restocking shipment's response
Add arrived_quantity damaged_quantity missing_quantity to restocking shipment item in the restocking shipment's response

2023-04-26

Add POST /skus/bulk_upsert endpoint

2023-04-19

Add fulfilled_by property to responses in SKUs endpoints

2023-04-18

Add batch_tracking_enabled property in SKUs endpoints' responses and accept it in POST/PATCH
Add /restocking_shipments endpoints

2023-04-14

Add inventory_batches property to responses in SKUs endpoints

2023-04-11

Add currency property in Orders endpoints' responses and accept it in POST/PATCH

{ "data": [ { "id": 70047, "return_reason_type": "active", "return_reason": "customer_return", "status": "handling_completed", "created_at": "2023-05-18T09:38:18.999+02:00", "received_at": "2023-05-19T10:38:18.999+02:00", "started_processing_at": "2023-05-20T11:38:18.999+02:00", "completed_handling_at": "2023-05-21T12:38:18.999+02:00", "tracking_code": "TC123456789", "tracking_url": "https://example.org/package?trackingNumber=TC123456789", "carrier": "ExampleCarrier", "order": { "id": 1230221, "merchant_order_id": "60423b95-23b5-4e5b-aa1c-6a71bd90b106", "name": "#DE12345" }, "photos": [ { "id": 115234, "photo_type": "outside", "image_url": "https://hive-production-images.s3.eu-central-1.amazonaws.com/a67e41b5fbfcf12264b3b4f704703678.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Credential=AKIA4LNZPVPUBMDZA65F%2F20230525%2Feu-central-1%2Fs3%2Faws4_request\u0026X-Amz-Date=20230525T083045Z\u0026X-Amz-Expires=900\u0026X-Amz-SignedHeaders=host\u0026X-Amz-Signature=d8e308229c3ee3e48d637f45e1594c5e47cf69e6b3b69c008e29685b8fcd3591" }, { "id": 115235, "photo_type": "inside", "image_url": "https://hive-production-images.s3.eu-central-1.amazonaws.com/a67e41b5fbfcf12264b3b4f704703679.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Credential=AKIA4LNZPVPUBMDZA65F%2F20230525%2Feu-central-1%2Fs3%2Faws4_request\u0026X-Amz-Date=20230525T083045Z\u0026X-Amz-Expires=900\u0026X-Amz-SignedHeaders=host\u0026X-Amz-Signature=d8e308229c3ee3e48d637f45e1594c5e47cf69e6b3b69c008e29685b8fcd3591" } ], "return_items": [ { "id": 27890, "quantity": 1, "customer_return_reason": "incorrect_product_arrived", "customer_return_message": "I ordered red pencil but got green one", "sku": { "id": 123085, "merchant_sku_id": "ABC123" } } ], "return_line_items": [ { "id": 10456, "inventory_batch_id": 123, "return_item_id": 27890, "condition": "A", "follow_up_action": "restock", "photos": [ { "id": 117781, "image_url": "https://hive-production-images.s3.eu-central-1.amazonaws.com/a67e41b5fbfcf12264b3b4f704703467.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Credential=AKIA4LNZPVPUBMDZA65F%2F20230525%2Feu-central-1%2Fs3%2Faws4_request\u0026X-Amz-Date=20230525T083045Z\u0026X-Amz-Expires=900\u0026X-Amz-SignedHeaders=host\u0026X-Amz-Signature=d8e308229c3ee3e48d637f45e1594c5e47cf69e6b3b69c008e29685b8fcd3591" } ], "sku": { "id": 123085, "merchant_sku_id": "ABC123" }, "quantity": 1 } ] } ], "pagination": { "current_page": 1, "item_count": 1, "items_per_page": 20, "page_count": 1 } }

{ "id": 70047, "return_reason_type": "active", "return_reason": "customer_return", "status": "handling_completed", "created_at": "2023-05-18T09:38:18.999+02:00", "received_at": "2023-05-19T10:38:18.999+02:00", "started_processing_at": "2023-05-20T11:38:18.999+02:00", "completed_handling_at": "2023-05-21T12:38:18.999+02:00", "tracking_code": "TC123456789", "tracking_url": "https://example.org/package?trackingNumber=TC123456789", "carrier": "ExampleCarrier", "order": { "id": 1230221, "merchant_order_id": "60423b95-23b5-4e5b-aa1c-6a71bd90b106" }, "photos": [ { "id": 115234, "photo_type": "outside", "image_url": "https://hive-production-images.s3.eu-central-1.amazonaws.com/a67e41b5fbfcf12264b3b4f704703678.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Credential=AKIA4LNZPVPUBMDZA65F%2F20230525%2Feu-central-1%2Fs3%2Faws4_request\u0026X-Amz-Date=20230525T083045Z\u0026X-Amz-Expires=900\u0026X-Amz-SignedHeaders=host\u0026X-Amz-Signature=d8e308229c3ee3e48d637f45e1594c5e47cf69e6b3b69c008e29685b8fcd3591" }, { "id": 115235, "photo_type": "inside", "image_url": "https://hive-production-images.s3.eu-central-1.amazonaws.com/a67e41b5fbfcf12264b3b4f704703679.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Credential=AKIA4LNZPVPUBMDZA65F%2F20230525%2Feu-central-1%2Fs3%2Faws4_request\u0026X-Amz-Date=20230525T083045Z\u0026X-Amz-Expires=900\u0026X-Amz-SignedHeaders=host\u0026X-Amz-Signature=d8e308229c3ee3e48d637f45e1594c5e47cf69e6b3b69c008e29685b8fcd3591" } ], "return_items": [ { "id": 27890, "quantity": 1, "customer_return_reason": "incorrect_product_arrived", "customer_return_message": "I ordered red pencil but got green one", "sku": { "id": 123085, "merchant_sku_id": "ABC123" } } ], "return_line_items": [ { "id": 10456, "inventory_batch_id": 123, "return_item_id": 27890, "condition": "A", "follow_up_action": "restock", "photos": [ { "id": 117781, "image_url": "https://hive-production-images.s3.eu-central-1.amazonaws.com/a67e41b5fbfcf12264b3b4f704703467.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Credential=AKIA4LNZPVPUBMDZA65F%2F20230525%2Feu-central-1%2Fs3%2Faws4_request\u0026X-Amz-Date=20230525T083045Z\u0026X-Amz-Expires=900\u0026X-Amz-SignedHeaders=host\u0026X-Amz-Signature=d8e308229c3ee3e48d637f45e1594c5e47cf69e6b3b69c008e29685b8fcd3591" } ], "sku": { "id": 123085, "merchant_sku_id": "ABC123" }, "quantity": 1 } ] }

SKUs

The SKU resource

Property

Type

Description

barcode

String

Barcode of the SKU

*Required properties when creating a new record.

The SkuInventory resource

Property

Type

Description

The SkuInventoryBatches resource

Property

Type

Description

The SkuInventoryPerWarehouse resource

Property

Type

Description

The InventoryPerWarehouse resource

Property

Type

Description

List all SKUs

GET https://app.hive.app/merchant_api/v1/skus

Returns SKUs ordered by descending creation time.

Query Parameters

Name

Type

Description

Create a new SKU

POST https://app.hive.app/merchant_api/v1/skus

Request Body

Name

Type

Description

Update an SKU

PATCH https://app.hive.app/merchant_api/v1/skus/{id}

Path Parameters

Name

Type

Description

Request Body

Name

Type

Description

Batch upsert SKUs

POST https://app.hive.app/merchant_api/v1/skus/bulk_upsert

For each item in the provided list, it creates an SKU if it does not exist yet on our side, updates if it already exists.

The endpoint accepts up to 100 items in the skus key of the request body. At least one should be provided. Each item should have the same structure as in the POST /skus endpoint. All fields except name and merchant_sku_id are optional.

If any field of an existing SKU already has a value set on our side (e.g. cost_in_cents=100) and you omit that field in the request, it will be set to null on our side. However, if batch_tracking_enabled is omitted in the request, its existing value will remain unchanged. To update batch_tracking_enabled, you must include it explicitly (true/false) in the request body.

Request Body

Name

Type

Description

Delete an SKU

DELETE https://app.hive.app/merchant_api/v1/skus/{id}

Marks an active SKU as "deleted". Will be set back to "active" on next create, update or batch upsert of that sku.

Path Parameters

Name

Type

Description

{ "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, "barcode": "2218061549136", "batch_tracking_enabled": true, "fulfilled_by": "hive", "weight_in_kg": 45.37, "image_url": "http://example.com/image.png", "status": "active", "dangerous_good": true, "un_numbers": ["UN3481"], "hazardous_good": false, "h_codes": [], "inventory": { "stocked": 10000, "reserved": 0, "total": 10000 }, "inventory_per_warehouse": [ { "warehouse_id": 22, "stocked": 6720, "reserved": 0, "total": 6720 }, { "warehouse_id": 65, "stocked": 3240, "reserved": 0, "total": 3240 }, { "warehouse_id": 38, "stocked": 40, "reserved": 0, "total": 40 } ], "inventory_batches": [ { "id": 827, "name": "Morph II - 827", "tracking_code": "A01234", "expiry_date": "2023-12-30", "stocked_quantities": [ { "warehouse_id": 22, "quantity": 6720 }, { "warehouse_id": 65, "quantity": 3240 } ] }, { "id": 674, "name": "Morph II - 674", "tracking_code": "B56789", "expiry_date": null, "stocked_quantities": [ { "warehouse_id": 38, "quantity": 40 } ] } ] }, { "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, "barcode": "2218061549136", "batch_tracking_enabled": false, "fulfilled_by": "hive", "weight_in_kg": 24.92, "image_url": "http://example.com/image.png", "status": "active", "dangerous_good": true, "un_numbers": ["UN3481"], "hazardous_good": false, "h_codes": [], "inventory": { "stocked": 10000, "reserved": 0, "total": 10000 }, "inventory_per_warehouse": [ { "warehouse_id": 22, "stocked": 10000, "reserved": 0, "total": 10000 }, { "warehouse_id": 65, "stocked": 0, "reserved": 0, "total": 0 } ], "inventory_batches": [] } ], "pagination": { "current_page": 1, "item_count": 2, "page_count": 1, "items_per_page": 20 } }

Restocking Shipments

The RestockingShipment resource

Property

Type

Description

barcode

String (read-only)

The barcode of the shipment

The RestockingShipmentItem resource

Property

Type

Description

The RestockingShipmentInventoryBatch resource

Property

Type

Description

*Required properties when creating a new record.

List all restocking shipments

List all Restocking Shipments

GET https://app.hive.app/merchant_api/v1/restocking_shipments

Returns restocking shipments ordered by descending creation time.

note: arrived_quantity, damaged_quantity and missing_quantity are visible only if the status is restocked

Get one restocking shipment

GET https://app.hive.app/merchant_api/v1/restocking_shipments/{id}

Path Parameters

Name

Type

Description

Create a new restocking shipment

Creates a new restocking shipment

POST https://app.hive.app/merchant_api/v1/restocking_shipments/

Request Body

Name

Type

Description

Update a restocking shipment

PUT https://app.hive.app/merchant_api/v1/restocking_shipments/{id}/

Replaces the whole resource. The restocking shipment can be updated only if the status is shipped or created

Path Parameters

Name

Type

Description

Request Body

Name

Type

Description

Cancel a restocking shipment

PUT https://app.hive.app/merchant_api/v1/restocking_shipments/{id}/cancel

The restocking shipment can be canceled only if the status is shipped or created

Query Parameters

Name

Type

Description

Hive Merchant API

Hive Merchant API

hashtagIntroduction

hashtagWant to jump right in?

hashtagWant to deep dive?

Quick Start

hashtagGet your API key

hashtagInstall a REST client

Changelog

Reference

API Reference

General

hashtagAuthentication

Shipments

hashtagThe Shipment resource

hashtagThe ShipmentItem resource

hashtagThe ShipmentItemBatch resource

hashtagThe ShipmentItemSerialNumber resource

hashtagThe ShipmentItemSku resource

hashtagList all shipments

hashtagLists all shipments of an order

hashtagQuery Parameters

Warehouses

hashtagThe Warehouse resource

Returns

hashtagThe Return resource

hashtagThe ReturnItem resource

hashtagThe ReturnLineItem resource

hashtagThe ReturnSku resource

hashtagThe ReturnOrder resource

hashtagThe ReturnPhoto resource

hashtagThe ReturnLineItemPhoto resource

hashtagList all returns

hashtagLists all order returns

hashtagQuery Parameters

hashtagGet one return

hashtagGet one specific order return

hashtagPath Parameters

Webhooks

hashtagSecurity

Hive Merchant API

hashtagIntroduction

hashtagWant to jump right in?

hashtagWant to deep dive?

Changelog

Quick Start

hashtagGet your API key

hashtagInstall a REST client

Warehouses

hashtagThe Warehouse resource

hashtagList all warehouses

hashtagLists all warehouses

Webhooks

hashtagSecurity

General

hashtagAuthentication

hashtagErrors

hashtagCommon errors

hashtagSuccessful responses

hashtagSingle object

hashtagCollection of objects

hashtagPagination

API Reference

Shipments

hashtagThe Shipment resource

hashtagThe ShipmentItem resource

hashtagThe ShipmentItemBatch resource

hashtagThe ShipmentItemSerialNumber resource

hashtagThe ShipmentItemSku resource

hashtagList all shipments

hashtagLists all shipments of an order

hashtagQuery Parameters

Returns

hashtagThe Return resource

hashtagThe ReturnItem resource

hashtagThe ReturnLineItem resource

hashtagThe ReturnSku resource

hashtagThe ReturnOrder resource

hashtagThe ReturnPhoto resource

hashtagThe ReturnLineItemPhoto resource

Introduction

Want to jump right in?

Want to deep dive?

Get your API key

Install a REST client

Authentication

The Shipment resource

The ShipmentItem resource

The ShipmentItemBatch resource

The ShipmentItemSerialNumber resource

The ShipmentItemSku resource

List all shipments

Lists all shipments of an order

Query Parameters

The Warehouse resource

The Return resource

The ReturnItem resource

The ReturnLineItem resource

The ReturnSku resource

The ReturnOrder resource

The ReturnPhoto resource

The ReturnLineItemPhoto resource

List all returns

Lists all order returns

Query Parameters

Get one return

Get one specific order return

Path Parameters

Security

Introduction

Want to jump right in?

Want to deep dive?

Get your API key

Install a REST client

The Warehouse resource

List all warehouses

Lists all warehouses

Security

Authentication

Errors

Common errors

Successful responses

Single object

Collection of objects

Pagination

The Shipment resource

The ShipmentItem resource

The ShipmentItemBatch resource

The ShipmentItemSerialNumber resource

The ShipmentItemSku resource

List all shipments

Lists all shipments of an order

Query Parameters

The Return resource

The ReturnItem resource

The ReturnLineItem resource

The ReturnSku resource

The ReturnOrder resource

The ReturnPhoto resource

The ReturnLineItemPhoto resource

List all returns

Lists all order returns

Query Parameters

Get one return

Get one specific order return

Path Parameters

The SKU resource

The SkuInventory resource

The SkuInventoryBatches resource

The SkuInventoryPerWarehouse resource

The InventoryPerWarehouse resource

List all SKUs

Query Parameters

Create a new SKU

Request Body

Update an SKU

Path Parameters

Request Body

Batch upsert SKUs

Request Body