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

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

List shipments

Request

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.

Security
BearerAuth
Query
limitinteger[ 1 .. 100 ]

Number of items to return per page (for pagination)

Default 20
order_id[in]Array of integers(int64)

Filter results by one or more Hive order IDs

merchant_order_id[in]Array of strings

Filter results by one or more merchant order IDs

curl -i -X GET \
  'https://hive-merchant-api.redocly.app/_mock/merchant-api-v2/mapi_v2_oas31/shipments?limit=20&order_id%5Bin%5D=0&merchant_order_id%5Bin%5D=string' \
  -H 'Authorization: Bearer <YOUR_token_HERE>'

Responses

A list of shipments

Bodyapplication/json
dataArray of objects(Shipment)
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"
  }
}

shipmentStatusUpdatedWebhookWebhook

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

Enum"shipment.status_updated""shipment.delivery_status_updated"
event_idstring(uuid)required

Unique identifier for this webhook event

timestampstring(date-time)required

When the event occurred

dataobject(Shipment)required
data.​created_atstring(date-time)read-only

When the shipment was created

data.​delivered_atstring or null(date-time)read-only

When the shipment was delivered

data.​delivery_statusShipmentDeliveryStatus (string) or null
Any of:

Delivery status of the shipment. Possible values:

  • action_required: Unconventional event (e.g. failed delivery, lost shipment, address issues)
  • awaiting_customer_pickup: Package is ready for customer pickup
  • delivered: Successfully delivered
  • in_transit: On the way to carrier hub
  • information_transmitted: Information sent to carrier (shipped but no carrier updates yet)
  • other: Unknown or other delivery status
  • out_for_delivery: Left carrier hub, being delivered
  • return_initiated: Return process has been initiated
  • returned_to_sender: Carrier initiated return to sender
string(ShipmentDeliveryStatus)read-only
Enum"action_required""awaiting_customer_pickup""delivered""in_transit""information_transmitted""other""out_for_delivery""return_initiated""returned_to_sender"
data.​idinteger(int64)read-onlyrequired

The shipment's unique identifier in Hive

data.​itemsArray of objects(ShipmentItem)required

Which line items this shipment includes

data.​items[].​batchesArray of objects(ShipmentItemBatch)

Which batches were sent for this line item

data.​items[].​idinteger(int64)required

The shipment item's unique identifier in Hive

data.​items[].​merchant_item_idstring or null

The order line item identifier as provided by the merchant. Will be null for items added later (e.g. via add-on rules).

data.​items[].​quantityinteger(int32)required

Number of SKUs in this line item

data.​items[].​serial_numbersArray of objects(ShipmentItemSerialNumber)

Which serial numbers were sent for this line item

data.​items[].​skuobject(ShipmentItemSku)required
data.​items[].​sku.​idinteger(int64)required

Hive unique identifier for the SKU

data.​items[].​sku.​sku_codestringrequired

SKU identifier as provided by the merchant

data.​merchant_order_idstring

Related order's unique identifier provided by merchant

data.​order_idinteger(int64)read-onlyrequired

Related order's unique identifier in Hive

data.​sales_channel_idinteger(int64)read-onlyrequired

The ID of the sales channel this shipment belongs to

data.​shipment_providerstring or null

Name of the shipment provider/carrier

data.​shipped_atstring or null(date-time)read-only

When the shipment was shipped

data.​shipping_methodstring or null
data.​statusstring(ShipmentStatus)read-onlyrequired
Enum"cancelled""in_packing""in_picking""in_shipping""on_hold""packed""picked""picking_assigned""shipped""waiting_for_picking"
data.​tracking_numberstring or null

Tracking number assigned by the shipment provider/carrier

data.​tracking_urlstring or null

Shipment provider website showing tracking information

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

When the shipment was updated

application/json
{
  "event_type": "shipment.status_updated",
  "event_id": "123e4567-e89b-12d3-a456-426614174001",
  "timestamp": "2023-10-01T15:00:00Z",
  "data": {
    "id": 789012,
    "order_id": 123456,
    "sales_channel_id": 10,
    "status": "shipped",
    "items": [ … ]
  }
}

Responses

Webhook received successfully

shipmentDeliveryStatusUpdatedWebhookWebhook

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

Enum"shipment.status_updated""shipment.delivery_status_updated"
event_idstring(uuid)required

Unique identifier for this webhook event

timestampstring(date-time)required

When the event occurred

dataobject(Shipment)required
data.​created_atstring(date-time)read-only

When the shipment was created

data.​delivered_atstring or null(date-time)read-only

When the shipment was delivered

data.​delivery_statusShipmentDeliveryStatus (string) or null
Any of:

Delivery status of the shipment. Possible values:

  • action_required: Unconventional event (e.g. failed delivery, lost shipment, address issues)
  • awaiting_customer_pickup: Package is ready for customer pickup
  • delivered: Successfully delivered
  • in_transit: On the way to carrier hub
  • information_transmitted: Information sent to carrier (shipped but no carrier updates yet)
  • other: Unknown or other delivery status
  • out_for_delivery: Left carrier hub, being delivered
  • return_initiated: Return process has been initiated
  • returned_to_sender: Carrier initiated return to sender
string(ShipmentDeliveryStatus)read-only
Enum"action_required""awaiting_customer_pickup""delivered""in_transit""information_transmitted""other""out_for_delivery""return_initiated""returned_to_sender"
data.​idinteger(int64)read-onlyrequired

The shipment's unique identifier in Hive

data.​itemsArray of objects(ShipmentItem)required

Which line items this shipment includes

data.​items[].​batchesArray of objects(ShipmentItemBatch)

Which batches were sent for this line item

data.​items[].​idinteger(int64)required

The shipment item's unique identifier in Hive

data.​items[].​merchant_item_idstring or null

The order line item identifier as provided by the merchant. Will be null for items added later (e.g. via add-on rules).

data.​items[].​quantityinteger(int32)required

Number of SKUs in this line item

data.​items[].​serial_numbersArray of objects(ShipmentItemSerialNumber)

Which serial numbers were sent for this line item

data.​items[].​skuobject(ShipmentItemSku)required
data.​items[].​sku.​idinteger(int64)required

Hive unique identifier for the SKU

data.​items[].​sku.​sku_codestringrequired

SKU identifier as provided by the merchant

data.​merchant_order_idstring

Related order's unique identifier provided by merchant

data.​order_idinteger(int64)read-onlyrequired

Related order's unique identifier in Hive

data.​sales_channel_idinteger(int64)read-onlyrequired

The ID of the sales channel this shipment belongs to

data.​shipment_providerstring or null

Name of the shipment provider/carrier

data.​shipped_atstring or null(date-time)read-only

When the shipment was shipped

data.​shipping_methodstring or null
data.​statusstring(ShipmentStatus)read-onlyrequired
Enum"cancelled""in_packing""in_picking""in_shipping""on_hold""packed""picked""picking_assigned""shipped""waiting_for_picking"
data.​tracking_numberstring or null

Tracking number assigned by the shipment provider/carrier

data.​tracking_urlstring or null

Shipment provider website showing tracking information

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

When the shipment was updated

application/json
{
  "event_type": "shipment.status_updated",
  "event_id": "123e4567-e89b-12d3-a456-426614174001",
  "timestamp": "2023-10-01T15:00:00Z",
  "data": {
    "id": 789012,
    "order_id": 123456,
    "sales_channel_id": 10,
    "status": "shipped",
    "items": [ … ]
  }
}

Responses

Webhook received successfully

Warehouses

Operations related to warehouses

Operations

Webhooks

Webhook event notifications

Webhooks