Skip to content

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.

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:

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.

Download OpenAPI description
mapi_v2_oas31.json
mapi_v2_oas31.yaml
Overview
URL

https://developers.hive.app

Hive Support

tech.api@hive.app

Languages
Servers
Mock server

https://hive-merchant-api.redocly.app/_mock/merchant-api-v2/mapi_v2_oas31/

Production API

https://app.hive.app/merchant_api/v2/

Staging API

https://staging.app.hive.app/merchant_api/v2/

InventoryTransferOrders

Operations related to inventory transfer orders

OperationsWebhooks

Orders

Operations related to orders

OperationsWebhooks

RestockingShipments

Operations related to restocking shipments

OperationsWebhooks

List restocking shipments

Request

Returns all restocking shipments for the merchant.

See the Pagination section in the API overview above for details on how pagination works.

Security
BearerAuth
Query
created_at[gt]string(date-time)

Filter results created after this date (ISO 8601 format)

created_at[lt]string(date-time)

Filter results created before this date (ISO 8601 format)

created_at[gte]string(date-time)

Filter results created on or after this date (ISO 8601 format)

created_at[lte]string(date-time)

Filter results created on or before this date (ISO 8601 format)

limitinteger[ 1 .. 100 ]

Number of items to return per page (for pagination)

Default 20
curl -i -X GET \
  'https://hive-merchant-api.redocly.app/_mock/merchant-api-v2/mapi_v2_oas31/restocking_shipments?created_at%5Bgt%5D=2019-08-24T14%3A15%3A22Z&created_at%5Blt%5D=2019-08-24T14%3A15%3A22Z&created_at%5Bgte%5D=2019-08-24T14%3A15%3A22Z&created_at%5Blte%5D=2019-08-24T14%3A15%3A22Z&limit=20' \
  -H 'Authorization: Bearer <YOUR_token_HERE>'

Responses

A list of restocking shipments

Bodyapplication/json
dataArray of objects(RestockingShipment)
paginationobject(Pagination)
Response
application/json
{
  "data": [
    { … }
  ],
  "pagination": {
    "first_page_url": "https://app.hive.app/merchant_api/v2/collection_of_items?limit=20",
    "limit": 20,
    "next_page_url": "https://app.hive.app/merchant_api/v2/collection_of_items?limit=20&page=eyJpZCI6MTIzNDU2fQ"
  }
}

Create a restocking shipment

Request

Creates a new restocking shipment for the merchant.

Security
BearerAuth
Bodyapplication/jsonrequired
delivery_optionstring(RestockingShipmentDeliveryOption)required
Enum"courier""dropoff""hive_freight""postal"
estimated_arrival_datestring(date)required

Estimated arrival date

po_numberstring

Purchase order number

restocking_shipment_itemsArray of objectsrequired

A list of items in the shipment. See RestockingShipmentItem.

Any of:
restocking_shipment_items[].​announced_quantityinteger(int32)>= 1required
restocking_shipment_items[].​remarksstring
restocking_shipment_items[].​sku_codestring

The merchant's SKU identifier - required if sku_id is not provided

restocking_shipment_items[].​sku_idinteger(int64)required

Hive SKU identifier - required if sku_code is not provided. If both are provided, sku_id will be used.

restocking_shipment_items[].​total_cost_in_centsinteger(int32)>= 0
supplier_namestring

Supplier name

tracking_codestring

Shipment tracking code

warehouse_idinteger(int64)required

The ID of the Hive destination warehouse

curl -i -X POST \
  https://hive-merchant-api.redocly.app/_mock/merchant-api-v2/mapi_v2_oas31/restocking_shipments \
  -H 'Authorization: Bearer <YOUR_token_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "delivery_option": "courier",
    "estimated_arrival_date": "2023-09-20",
    "po_number": "PO-2023-001",
    "restocking_shipment_items": [
      {
        "sku_id": 1001,
        "sku_code": "SKU-001",
        "announced_quantity": 50,
        "remarks": "All items in good condition",
        "total_cost_in_cents": 50000
      }
    ],
    "supplier_name": "Acme Supplies",
    "tracking_code": "TRACK-12345",
    "warehouse_id": 2
  }'

Responses

Restocking shipment created successfully

Bodyapplication/json
arrived_atstring or null(date-time)read-only

When the shipment was arrived

barcodestring or null

The barcode of the shipment

created_atstring(date-time)read-only

When the shipment was created

delivery_optionstring(RestockingShipmentDeliveryOption)
Enum"courier""dropoff""hive_freight""postal"
estimated_arrival_datestring or null(date)

Estimated arrival date

idinteger(int64)read-onlyrequired

Hive's unique identifier

po_numberstring or null

Purchase order number

restocking_shipment_itemsArray of objects(RestockingShipmentItem)required

A list of items in the shipment. See RestockingShipmentItem.

restocking_shipment_items[].​announced_quantityinteger(int32)>= 0

Quantity of this item in the shipment

restocking_shipment_items[].​arrived_quantityinteger(int32)>= 0required

Arrived quantity of this item (after shipment is received)

restocking_shipment_items[].​damaged_quantityinteger(int32)>= 0required

Damaged quantity of this item (after shipment is received)

restocking_shipment_items[].​idinteger(int64)

Hive's unique identifier

restocking_shipment_items[].​missing_quantityinteger(int32)>= 0required

Missing quantity of this item (after shipment is received)

restocking_shipment_items[].​remarksstring or null

Free text for remarks

restocking_shipment_items[].​sku_codestringrequired

The merchant's SKU identifier - required if sku_id is not provided

restocking_shipment_items[].​sku_idinteger(int64)required

Hive SKU identifier - required if sku_code is not provided

restocking_shipment_items[].​total_cost_in_centsinteger or null(int32)>= 0

Cost in cents

statusstring(RestockingShipmentStatus)read-onlyrequired
Enum"arrived""cancelled""created""processing""received""restocked""shipped"
supplier_namestring or null

Supplier name

tracking_codestring or null

Shipment tracking code

updated_atstring(date-time)read-only

When the shipment was last updated

warehouse_idinteger(int64)read-onlyrequired

The ID of the Hive destination warehouse

Response
application/json
{
  "id": 98765,
  "barcode": "SHIP-2023-0001",
  "created_at": "2023-09-15T09:00:00Z",
  "delivery_option": "courier",
  "estimated_arrival_date": "2023-09-20",
  "po_number": "PO-2023-001",
  "restocking_shipment_items": [
    { … }
  ],
  "status": "arrived",
  "supplier_name": "Acme Supplies",
  "tracking_code": "TRACK-12345",
  "updated_at": "2023-09-20T10:00:00Z",
  "warehouse_id": 2
}

Get a restocking shipment

Request

Returns a specific restocking shipment.

Security
BearerAuth
Path
idinteger(int64)required

Restocking Shipment ID

curl -i -X GET \
  'https://hive-merchant-api.redocly.app/_mock/merchant-api-v2/mapi_v2_oas31/restocking_shipments/{id}' \
  -H 'Authorization: Bearer <YOUR_token_HERE>'

Responses

A restocking shipment

Bodyapplication/json
arrived_atstring or null(date-time)read-only

When the shipment was arrived

barcodestring or null

The barcode of the shipment

created_atstring(date-time)read-only

When the shipment was created

delivery_optionstring(RestockingShipmentDeliveryOption)
Enum"courier""dropoff""hive_freight""postal"
estimated_arrival_datestring or null(date)

Estimated arrival date

idinteger(int64)read-onlyrequired

Hive's unique identifier

po_numberstring or null

Purchase order number

restocking_shipment_itemsArray of objects(RestockingShipmentItem)required

A list of items in the shipment. See RestockingShipmentItem.

restocking_shipment_items[].​announced_quantityinteger(int32)>= 0

Quantity of this item in the shipment

restocking_shipment_items[].​arrived_quantityinteger(int32)>= 0required

Arrived quantity of this item (after shipment is received)

restocking_shipment_items[].​damaged_quantityinteger(int32)>= 0required

Damaged quantity of this item (after shipment is received)

restocking_shipment_items[].​idinteger(int64)

Hive's unique identifier

restocking_shipment_items[].​missing_quantityinteger(int32)>= 0required

Missing quantity of this item (after shipment is received)

restocking_shipment_items[].​remarksstring or null

Free text for remarks

restocking_shipment_items[].​sku_codestringrequired

The merchant's SKU identifier - required if sku_id is not provided

restocking_shipment_items[].​sku_idinteger(int64)required

Hive SKU identifier - required if sku_code is not provided

restocking_shipment_items[].​total_cost_in_centsinteger or null(int32)>= 0

Cost in cents

statusstring(RestockingShipmentStatus)read-onlyrequired
Enum"arrived""cancelled""created""processing""received""restocked""shipped"
supplier_namestring or null

Supplier name

tracking_codestring or null

Shipment tracking code

updated_atstring(date-time)read-only

When the shipment was last updated

warehouse_idinteger(int64)read-onlyrequired

The ID of the Hive destination warehouse

Response
application/json
{
  "id": 98765,
  "barcode": "SHIP-2023-0001",
  "created_at": "2023-09-15T09:00:00Z",
  "delivery_option": "courier",
  "estimated_arrival_date": "2023-09-20",
  "po_number": "PO-2023-001",
  "restocking_shipment_items": [
    { … }
  ],
  "status": "arrived",
  "supplier_name": "Acme Supplies",
  "tracking_code": "TRACK-12345",
  "updated_at": "2023-09-20T10:00:00Z",
  "warehouse_id": 2
}

Update a restocking shipment (replace only, allowed if status is "shipped" or "created")

Request

Updates an existing restocking shipment. Only allowed if the shipment status is "shipped" or "created". This operation replaces the entire resource.

Security
BearerAuth
Path
idinteger(int64)required

Restocking Shipment ID

Bodyapplication/jsonrequired
delivery_optionstring(RestockingShipmentDeliveryOption)
Enum"courier""dropoff""hive_freight""postal"
estimated_arrival_datestring(date)

Estimated arrival date

po_numberstring

Purchase order number

restocking_shipment_itemsArray of objects

A list of items in the shipment. See RestockingShipmentItem.

supplier_namestring

Supplier name

tracking_codestring

Shipment tracking code

warehouse_idinteger(int64)

The ID of the Hive destination warehouse

curl -i -X PUT \
  'https://hive-merchant-api.redocly.app/_mock/merchant-api-v2/mapi_v2_oas31/restocking_shipments/{id}' \
  -H 'Authorization: Bearer <YOUR_token_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "delivery_option": "courier",
    "estimated_arrival_date": "2023-09-20",
    "po_number": "PO-2023-001",
    "restocking_shipment_items": [
      {
        "sku_id": 1001,
        "sku_code": "SKU-001",
        "announced_quantity": 50,
        "remarks": "All items in good condition",
        "total_cost_in_cents": 50000
      }
    ],
    "supplier_name": "Acme Supplies",
    "tracking_code": "TRACK-12345",
    "warehouse_id": 2
  }'

Responses

Restocking shipment updated successfully

Bodyapplication/json
arrived_atstring or null(date-time)read-only

When the shipment was arrived

barcodestring or null

The barcode of the shipment

created_atstring(date-time)read-only

When the shipment was created

delivery_optionstring(RestockingShipmentDeliveryOption)
Enum"courier""dropoff""hive_freight""postal"
estimated_arrival_datestring or null(date)

Estimated arrival date

idinteger(int64)read-onlyrequired

Hive's unique identifier

po_numberstring or null

Purchase order number

restocking_shipment_itemsArray of objects(RestockingShipmentItem)required

A list of items in the shipment. See RestockingShipmentItem.

restocking_shipment_items[].​announced_quantityinteger(int32)>= 0

Quantity of this item in the shipment

restocking_shipment_items[].​arrived_quantityinteger(int32)>= 0required

Arrived quantity of this item (after shipment is received)

restocking_shipment_items[].​damaged_quantityinteger(int32)>= 0required

Damaged quantity of this item (after shipment is received)

restocking_shipment_items[].​idinteger(int64)

Hive's unique identifier

restocking_shipment_items[].​missing_quantityinteger(int32)>= 0required

Missing quantity of this item (after shipment is received)

restocking_shipment_items[].​remarksstring or null

Free text for remarks

restocking_shipment_items[].​sku_codestringrequired

The merchant's SKU identifier - required if sku_id is not provided

restocking_shipment_items[].​sku_idinteger(int64)required

Hive SKU identifier - required if sku_code is not provided

restocking_shipment_items[].​total_cost_in_centsinteger or null(int32)>= 0

Cost in cents

statusstring(RestockingShipmentStatus)read-onlyrequired
Enum"arrived""cancelled""created""processing""received""restocked""shipped"
supplier_namestring or null

Supplier name

tracking_codestring or null

Shipment tracking code

updated_atstring(date-time)read-only

When the shipment was last updated

warehouse_idinteger(int64)read-onlyrequired

The ID of the Hive destination warehouse

Response
application/json
{
  "id": 98765,
  "barcode": "SHIP-2023-0001",
  "created_at": "2023-09-15T09:00:00Z",
  "delivery_option": "courier",
  "estimated_arrival_date": "2023-09-20",
  "po_number": "PO-2023-001",
  "restocking_shipment_items": [
    { … }
  ],
  "status": "arrived",
  "supplier_name": "Acme Supplies",
  "tracking_code": "TRACK-12345",
  "updated_at": "2023-09-20T10:00:00Z",
  "warehouse_id": 2
}

Cancel a restocking shipment

Request

Cancels an existing restocking shipment.

Security
BearerAuth
Path
idinteger(int64)required

Restocking Shipment ID

curl -i -X PUT \
  'https://hive-merchant-api.redocly.app/_mock/merchant-api-v2/mapi_v2_oas31/restocking_shipments/{id}/cancel' \
  -H 'Authorization: Bearer <YOUR_token_HERE>'

Responses

Restocking shipment cancelled successfully

Bodyapplication/json
object
Response
application/json
{}

restockingShipmentStatusUpdatedWebhookWebhook

Request

Security
BearerAuth
Headers
x-hive-signaturestringrequired

HMAC-SHA256 signature of the request body using your API token as the key

Bodyapplication/json
event_typestringrequired

The type of webhook event

Value"restocking_shipment.status_updated"
event_idstring(uuid)required

Unique identifier for this webhook event

timestampstring(date-time)required

When the event occurred

dataobject(RestockingShipment)required
data.​arrived_atstring or null(date-time)read-only

When the shipment was arrived

data.​barcodestring or null

The barcode of the shipment

data.​created_atstring(date-time)read-only

When the shipment was created

data.​delivery_optionstring(RestockingShipmentDeliveryOption)
Enum"courier""dropoff""hive_freight""postal"
data.​estimated_arrival_datestring or null(date)

Estimated arrival date

data.​idinteger(int64)read-onlyrequired

Hive's unique identifier

data.​po_numberstring or null

Purchase order number

data.​restocking_shipment_itemsArray of objects(RestockingShipmentItem)required

A list of items in the shipment. See RestockingShipmentItem.

data.​restocking_shipment_items[].​announced_quantityinteger(int32)>= 0

Quantity of this item in the shipment

data.​restocking_shipment_items[].​arrived_quantityinteger(int32)>= 0required

Arrived quantity of this item (after shipment is received)

data.​restocking_shipment_items[].​damaged_quantityinteger(int32)>= 0required

Damaged quantity of this item (after shipment is received)

data.​restocking_shipment_items[].​idinteger(int64)

Hive's unique identifier

data.​restocking_shipment_items[].​missing_quantityinteger(int32)>= 0required

Missing quantity of this item (after shipment is received)

data.​restocking_shipment_items[].​remarksstring or null

Free text for remarks

data.​restocking_shipment_items[].​sku_codestringrequired

The merchant's SKU identifier - required if sku_id is not provided

data.​restocking_shipment_items[].​sku_idinteger(int64)required

Hive SKU identifier - required if sku_code is not provided

data.​restocking_shipment_items[].​total_cost_in_centsinteger or null(int32)>= 0

Cost in cents

data.​statusstring(RestockingShipmentStatus)read-onlyrequired
Enum"arrived""cancelled""created""processing""received""restocked""shipped"
data.​supplier_namestring or null

Supplier name

data.​tracking_codestring or null

Shipment tracking code

data.​updated_atstring(date-time)read-only

When the shipment was last updated

data.​warehouse_idinteger(int64)read-onlyrequired

The ID of the Hive destination warehouse

application/json
{
  "event_type": "restocking_shipment.status_updated",
  "event_id": "123e4567-e89b-12d3-a456-426614174003",
  "timestamp": "2023-10-01T16:00:00Z",
  "data": {
    "id": 98765,
    "status": "arrived",
    "warehouse_id": 2,
    "restocking_shipment_items": [ … ]
  }
}

Responses

Webhook received successfully

Returns

Operations related to returns

OperationsWebhooks

SKUs

Operations related to Stock Keeping Units (SKUs)

Operations

SalesChannels

Operations related to sales channels

Operations

Shipments

Operations related to shipments

OperationsWebhooks

Warehouses

Operations related to warehouses

Operations

Webhooks

Webhook event notifications

Webhooks