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

List returns

Request

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.

Security
BearerAuth
Query
sales_channel_id[in]Array of integers(int64)

Filter results by one or more sales channel ID

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/returns?sales_channel_id%5Bin%5D=0&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 returns

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

Get a return

Request

Returns a specific return.

Security
BearerAuth
Path
idinteger(int64)required

Return ID

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

Responses

A return

Bodyapplication/json
announced_itemsArray of objects(ReturnAnnouncedItem)required

List of items announced by the customer (via the Customer Portal). Can be empty if the return is not a Customer Portal return.

announced_items[].​customer_return_messagestring

Reason details provided by the customer

announced_items[].​customer_return_reasonstring

Reason provided by the customer

announced_items[].​idintegerrequired

Hive's unique identifier

announced_items[].​quantityinteger>= 1required

Quantity of items announced

announced_items[].​skuobject(ReturnSku)required
announced_items[].​sku.​idintegerrequired

Hive's unique SKU identifier

announced_items[].​sku.​sku_codestringrequired

Merchant's SKU code

carrierstring or null

Carrier name

completed_handling_atstring or null(date-time)

When the return handling finished

created_atstring(date-time)required

When the return was created

handled_itemsArray of objects(ReturnHandledItem)

List of items that were actually handled in the FC. Can be empty if return items have not been handled in the FC yet.

idinteger(int64)required

Hive's unique identifier

orderobject(ReturnOrder)required
order.​customer_order_numberstringrequired

Customer's order identifier

order.​idintegerrequired

Hive's unique order identifier

order.​merchant_order_idstringrequired

Merchant's unique order identifier

photosArray of objects(ReturnPhoto)

Photos of the returned items

received_atstring or null(date-time)

When the return was received

return_reasonReturnReason (string) or null
Any of:

Reason for the return. Possible values:

  • customer_return: Customer initiated return
  • customs_documents_missing: Missing customs documentation
  • invalid_address: Invalid shipping address
  • not_picked_up: Package was not picked up by customer
  • other: Other reason not specified
  • rejected_by_customer: Customer rejected the delivery
string(ReturnReason)
Enum"customer_return""customs_documents_missing""invalid_address""not_picked_up""other""rejected_by_customer"
return_reason_typeReturnReasonType (string) or null
Any of:

Type of return categorization. Possible values:

  • active: Customer return (end-customer actively shipped the return)
  • passive: Carrier return (end-customer never received the parcel - shipped back by carrier for reasons like invalid address, not picked up, damages, missing customs documents, etc.)
string(ReturnReasonType)
Enum"active""passive"
started_processing_atstring or null(date-time)

When processing at the fulfillment center started

statusstring(ReturnStatus)read-onlyrequired
Enum"action_required""arrived""handling_completed""on_the_way""processing"
tracking_codestring or null

Tracking number assigned by the carrier

tracking_urlstring or null

Carrier website showing tracking information

updated_atstring(date-time)required
Response
application/json
{
  "id": 5555,
  "announced_items": [
    { … }
  ],
  "carrier": "DHL",
  "completed_handling_at": "2023-10-10T15:00:00Z",
  "created_at": "2023-10-08T10:00:00Z",
  "handled_items": [
    { … }
  ],
  "order": {
    "id": 123456,
    "merchant_order_id": "ORD-1001",
    "customer_order_number": "CUST-ORD-2023-01"
  },
  "photos": [
    { … }
  ],
  "received_at": "2023-10-09T12:00:00Z",
  "return_reason": "customer_return",
  "return_reason_type": "active",
  "started_processing_at": "2023-10-09T13:00:00Z",
  "status": "arrived",
  "tracking_code": "TRACK-RET-123",
  "tracking_url": "https://dhl.com/track/RET-123",
  "updated_at": "2023-10-10T15:00:00Z"
}

returnStatusUpdatedWebhookWebhook

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"return.status_updated"
event_idstring(uuid)required

Unique identifier for this webhook event

timestampstring(date-time)required

When the event occurred

dataobject(Return)required
data.​announced_itemsArray of objects(ReturnAnnouncedItem)required

List of items announced by the customer (via the Customer Portal). Can be empty if the return is not a Customer Portal return.

data.​announced_items[].​customer_return_messagestring

Reason details provided by the customer

data.​announced_items[].​customer_return_reasonstring

Reason provided by the customer

data.​announced_items[].​idintegerrequired

Hive's unique identifier

data.​announced_items[].​quantityinteger>= 1required

Quantity of items announced

data.​announced_items[].​skuobject(ReturnSku)required
data.​announced_items[].​sku.​idintegerrequired

Hive's unique SKU identifier

data.​announced_items[].​sku.​sku_codestringrequired

Merchant's SKU code

data.​carrierstring or null

Carrier name

data.​completed_handling_atstring or null(date-time)

When the return handling finished

data.​created_atstring(date-time)required

When the return was created

data.​handled_itemsArray of objects(ReturnHandledItem)

List of items that were actually handled in the FC. Can be empty if return items have not been handled in the FC yet.

data.​idinteger(int64)required

Hive's unique identifier

data.​orderobject(ReturnOrder)required
data.​order.​customer_order_numberstringrequired

Customer's order identifier

data.​order.​idintegerrequired

Hive's unique order identifier

data.​order.​merchant_order_idstringrequired

Merchant's unique order identifier

data.​photosArray of objects(ReturnPhoto)

Photos of the returned items

data.​received_atstring or null(date-time)

When the return was received

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

Reason for the return. Possible values:

  • customer_return: Customer initiated return
  • customs_documents_missing: Missing customs documentation
  • invalid_address: Invalid shipping address
  • not_picked_up: Package was not picked up by customer
  • other: Other reason not specified
  • rejected_by_customer: Customer rejected the delivery
string(ReturnReason)
Enum"customer_return""customs_documents_missing""invalid_address""not_picked_up""other""rejected_by_customer"
data.​return_reason_typeReturnReasonType (string) or null
Any of:

Type of return categorization. Possible values:

  • active: Customer return (end-customer actively shipped the return)
  • passive: Carrier return (end-customer never received the parcel - shipped back by carrier for reasons like invalid address, not picked up, damages, missing customs documents, etc.)
string(ReturnReasonType)
Enum"active""passive"
data.​started_processing_atstring or null(date-time)

When processing at the fulfillment center started

data.​statusstring(ReturnStatus)read-onlyrequired
Enum"action_required""arrived""handling_completed""on_the_way""processing"
data.​tracking_codestring or null

Tracking number assigned by the carrier

data.​tracking_urlstring or null

Carrier website showing tracking information

data.​updated_atstring(date-time)required
application/json
{
  "event_type": "return.status_updated",
  "event_id": "123e4567-e89b-12d3-a456-426614174002",
  "timestamp": "2023-10-01T18:00:00Z",
  "data": {
    "id": 5555,
    "status": "arrived",
    "created_at": "2023-10-01T18:00:00Z",
    "updated_at": "2023-10-01T18:00:00Z",
    "announced_items": [ … ],
    "order": { … }
  }
}

Responses

Webhook received successfully

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