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

List SKUs

Request

Returns all SKUs 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
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)

sku_code[in]Array of strings

Filter results by one or more merchant SKU codes

curl -i -X GET \
  'https://hive-merchant-api.redocly.app/_mock/merchant-api-v2/mapi_v2_oas31/skus?limit=20&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&sku_code%5Bin%5D=string' \
  -H 'Authorization: Bearer <YOUR_token_HERE>'

Responses

A list of SKUs

Bodyapplication/json
dataArray of objects(Sku)
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 new SKU

Request

Creates a new SKU for the merchant. SKUs must have a unique SKU code. New SKUs are marked as "verified" and fulfilled_by "hive".

Security
BearerAuth
Bodyapplication/jsonrequired
barcodestring or nullnon-empty

The SKU barcode

batch_tracking_enabledboolean

Enables inventory tracking per batch (defaults to false if omitted)

cost_in_centsinteger or null>= 0

The cost (not price) of this SKU

country_code_of_originstring or null^[A-Z]{2}$

2-letter ISO 3166-1 code of country of origin

hs_codestring or null

Harmonized System code

image_urlstring or null

Image of the product, must be publicly accessible.

namestringnon-emptyrequired

A human-readable name or title

sku_codestringnon-emptyrequired

An ID that uniquely identifies this SKU

weight_in_kgnumber or null>= 0
Any of:

Weight in kilograms

>= 0
number>= 0
curl -i -X POST \
  https://hive-merchant-api.redocly.app/_mock/merchant-api-v2/mapi_v2_oas31/skus \
  -H 'Authorization: Bearer <YOUR_token_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "T-Shirt Black M",
    "sku_code": "SKU-001",
    "barcode": "1234567890123",
    "batch_tracking_enabled": false,
    "cost_in_cents": 800,
    "country_code_of_origin": "DE",
    "hs_code": "610910",
    "image_url": "https://cdn.hive.app/skus/sku-001.jpg",
    "weight_in_kg": 0.2
  }'

Responses

SKU created successfully

Bodyapplication/json
barcodestring or nullnon-empty

Barcode of the SKU

batch_tracking_enabledbooleanrequired

Whether batch tracking of this SKU is enabled

cost_in_centsinteger or null>= 0

Cost in cents (currency of the shop is implied)

country_code_of_originstring or null^[A-Z]{2}$

2-letter ISO 3166-1 code of country of origin

created_atstring(date-time)read-onlyrequired

When this SKU was created

updated_atstring(date-time)read-onlyrequired

When this SKU was last updated

dangerous_goodbooleanrequired

Sku is a dangerous good

fulfilled_bystring(SkuFulfilledBy)required
Enum"hive""new""other"
h_codesArray of stringsrequired

Hazardous good H Codes

hazardous_goodbooleanrequired

SKU is a hazardous good

hs_codestring or null

The general Harmonized System (HS) code for the SKU

idinteger(int64)read-onlyrequired

Hive unique identifier for this SKU

image_urlstring or null

Publicly accessible URL of an image for this SKU

inventoryobject(SkuInventory)required
inventory.​availableintegerrequired

Quantity available for sale (stocked minus reserved)

inventory.​reservedinteger>= 0required

Quantity reserved/committed for orders

inventory.​stockedinteger>= 0required

Quantity in the warehouse (available plus reserved)

inventory_batchesArray of objects(SkuInventoryBatch)required

Current inventory per batch

inventory_batches[].​expiry_datestring or null(date)required

Expiration date of the batch (ISO8601 date, read-only)

inventory_batches[].​idintegerrequired

Hive unique ID for the batch (read-only)

inventory_batches[].​namestringrequired

Name of the batch (read-only)

inventory_batches[].​stocked_quantitiesArray of objects(SkuInventoryBatchQuantityPerWarehouse)required

Inventory per warehouse for this batch (see SkuInventoryBatchQuantityPerWarehouse) (read-only)

inventory_batches[].​stocked_quantities[].​stockedinteger>= 0required

Quantity in the warehouse for this batch in this warehouse

inventory_batches[].​stocked_quantities[].​warehouse_idintegerrequired

Hive's unique warehouse ID

inventory_batches[].​tracking_codestringrequired

Tracking code (read-only)

inventory_per_warehouseArray of objects(SkuInventoryPerWarehouse)required

Current inventory per warehouse

inventory_per_warehouse[].​availableintegerrequired

Quantity available for sale (stocked minus reserved)

inventory_per_warehouse[].​reservedinteger>= 0required

Quantity reserved/committed for orders

inventory_per_warehouse[].​stockedinteger>= 0required

Quantity in the warehouse (available plus reserved)

inventory_per_warehouse[].​warehouse_idintegerrequired

Hive's unique warehouse ID

namestringrequired

Name of this SKU

sku_codestringrequired

SKU code - visible in the UI

statusstring(SkuStatus)required
Enum"active""deleted"
un_numbersArray of stringsrequired

Dangerous good UN Numbers

weight_in_kgnumber or null>= 0required
Any of:

Weight of SKU in kilograms

>= 0
number>= 0
Response
application/json
{
  "id": 1001,
  "name": "T-Shirt Black M",
  "sku_code": "SKU-001",
  "barcode": "1234567890123",
  "batch_tracking_enabled": false,
  "cost_in_cents": 800,
  "country_code_of_origin": "DE",
  "created_at": "2023-09-01T08:00:00Z",
  "updated_at": "2023-10-01T14:30:00Z",
  "dangerous_good": false,
  "fulfilled_by": "hive",
  "h_codes": [],
  "hazardous_good": false,
  "hs_code": "610910",
  "image_url": "https://cdn.hive.app/skus/sku-001.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA4%&X-Amz-Date=20230525T083045Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=d8e3",
  "inventory": {
    "available": 90,
    "reserved": 10,
    "stocked": 100
  },
  "inventory_batches": [],
  "inventory_per_warehouse": [
    { … }
  ],
  "status": "active",
  "un_numbers": [],
  "weight_in_kg": 0.2
}

Delete a SKU

Request

Deletes an existing SKU.

Security
BearerAuth
Path
idinteger(int64)required

SKU ID

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

Responses

SKU deleted successfully

Response
No content

Get a SKU by ID

Request

Returns a specific SKU by its ID.

Security
BearerAuth
Path
idinteger(int64)required

SKU ID

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

Responses

A SKU

Bodyapplication/json
barcodestring or nullnon-empty

Barcode of the SKU

batch_tracking_enabledbooleanrequired

Whether batch tracking of this SKU is enabled

cost_in_centsinteger or null>= 0

Cost in cents (currency of the shop is implied)

country_code_of_originstring or null^[A-Z]{2}$

2-letter ISO 3166-1 code of country of origin

created_atstring(date-time)read-onlyrequired

When this SKU was created

updated_atstring(date-time)read-onlyrequired

When this SKU was last updated

dangerous_goodbooleanrequired

Sku is a dangerous good

fulfilled_bystring(SkuFulfilledBy)required
Enum"hive""new""other"
h_codesArray of stringsrequired

Hazardous good H Codes

hazardous_goodbooleanrequired

SKU is a hazardous good

hs_codestring or null

The general Harmonized System (HS) code for the SKU

idinteger(int64)read-onlyrequired

Hive unique identifier for this SKU

image_urlstring or null

Publicly accessible URL of an image for this SKU

inventoryobject(SkuInventory)required
inventory.​availableintegerrequired

Quantity available for sale (stocked minus reserved)

inventory.​reservedinteger>= 0required

Quantity reserved/committed for orders

inventory.​stockedinteger>= 0required

Quantity in the warehouse (available plus reserved)

inventory_batchesArray of objects(SkuInventoryBatch)required

Current inventory per batch

inventory_batches[].​expiry_datestring or null(date)required

Expiration date of the batch (ISO8601 date, read-only)

inventory_batches[].​idintegerrequired

Hive unique ID for the batch (read-only)

inventory_batches[].​namestringrequired

Name of the batch (read-only)

inventory_batches[].​stocked_quantitiesArray of objects(SkuInventoryBatchQuantityPerWarehouse)required

Inventory per warehouse for this batch (see SkuInventoryBatchQuantityPerWarehouse) (read-only)

inventory_batches[].​stocked_quantities[].​stockedinteger>= 0required

Quantity in the warehouse for this batch in this warehouse

inventory_batches[].​stocked_quantities[].​warehouse_idintegerrequired

Hive's unique warehouse ID

inventory_batches[].​tracking_codestringrequired

Tracking code (read-only)

inventory_per_warehouseArray of objects(SkuInventoryPerWarehouse)required

Current inventory per warehouse

inventory_per_warehouse[].​availableintegerrequired

Quantity available for sale (stocked minus reserved)

inventory_per_warehouse[].​reservedinteger>= 0required

Quantity reserved/committed for orders

inventory_per_warehouse[].​stockedinteger>= 0required

Quantity in the warehouse (available plus reserved)

inventory_per_warehouse[].​warehouse_idintegerrequired

Hive's unique warehouse ID

namestringrequired

Name of this SKU

sku_codestringrequired

SKU code - visible in the UI

statusstring(SkuStatus)required
Enum"active""deleted"
un_numbersArray of stringsrequired

Dangerous good UN Numbers

weight_in_kgnumber or null>= 0required
Any of:

Weight of SKU in kilograms

>= 0
number>= 0
Response
application/json
{
  "id": 1001,
  "name": "T-Shirt Black M",
  "sku_code": "SKU-001",
  "barcode": "1234567890123",
  "batch_tracking_enabled": false,
  "cost_in_cents": 800,
  "country_code_of_origin": "DE",
  "created_at": "2023-09-01T08:00:00Z",
  "updated_at": "2023-10-01T14:30:00Z",
  "dangerous_good": false,
  "fulfilled_by": "hive",
  "h_codes": [],
  "hazardous_good": false,
  "hs_code": "610910",
  "image_url": "https://cdn.hive.app/skus/sku-001.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA4%&X-Amz-Date=20230525T083045Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=d8e3",
  "inventory": {
    "available": 90,
    "reserved": 10,
    "stocked": 100
  },
  "inventory_batches": [],
  "inventory_per_warehouse": [
    { … }
  ],
  "status": "active",
  "un_numbers": [],
  "weight_in_kg": 0.2
}

Partially update a SKU

Request

Partially updates an existing SKU. Only the provided fields will be updated.

Security
BearerAuth
Path
idinteger(int64)required

SKU ID

Bodyapplication/jsonrequired
barcodestring or nullnon-empty

The SKU barcode

batch_tracking_enabledboolean

Enables inventory tracking per batch (defaults to false if omitted)

cost_in_centsinteger or null>= 0

The cost (not price) of this SKU

country_code_of_originstring or null^[A-Z]{2}$

2-letter ISO 3166-1 code of country of origin

hs_codestring or null

Harmonized System code

image_urlstring or null

Image of the product, must be publicly accessible.

namestringnon-empty

A human-readable name or title

sku_codestringnon-empty

An ID that uniquely identifies this SKU

weight_in_kgnumber or null>= 0
Any of:

Weight in kilograms

>= 0
number>= 0
curl -i -X PATCH \
  'https://hive-merchant-api.redocly.app/_mock/merchant-api-v2/mapi_v2_oas31/skus/{id}' \
  -H 'Authorization: Bearer <YOUR_token_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "T-Shirt Black M",
    "sku_code": "SKU-001",
    "barcode": "1234567890123",
    "batch_tracking_enabled": false,
    "cost_in_cents": 800,
    "country_code_of_origin": "DE",
    "hs_code": "610910",
    "image_url": "https://cdn.hive.app/skus/sku-001.jpg",
    "weight_in_kg": 0.2
  }'

Responses

SKU updated successfully

Bodyapplication/json
barcodestring or nullnon-empty

Barcode of the SKU

batch_tracking_enabledbooleanrequired

Whether batch tracking of this SKU is enabled

cost_in_centsinteger or null>= 0

Cost in cents (currency of the shop is implied)

country_code_of_originstring or null^[A-Z]{2}$

2-letter ISO 3166-1 code of country of origin

created_atstring(date-time)read-onlyrequired

When this SKU was created

updated_atstring(date-time)read-onlyrequired

When this SKU was last updated

dangerous_goodbooleanrequired

Sku is a dangerous good

fulfilled_bystring(SkuFulfilledBy)required
Enum"hive""new""other"
h_codesArray of stringsrequired

Hazardous good H Codes

hazardous_goodbooleanrequired

SKU is a hazardous good

hs_codestring or null

The general Harmonized System (HS) code for the SKU

idinteger(int64)read-onlyrequired

Hive unique identifier for this SKU

image_urlstring or null

Publicly accessible URL of an image for this SKU

inventoryobject(SkuInventory)required
inventory.​availableintegerrequired

Quantity available for sale (stocked minus reserved)

inventory.​reservedinteger>= 0required

Quantity reserved/committed for orders

inventory.​stockedinteger>= 0required

Quantity in the warehouse (available plus reserved)

inventory_batchesArray of objects(SkuInventoryBatch)required

Current inventory per batch

inventory_batches[].​expiry_datestring or null(date)required

Expiration date of the batch (ISO8601 date, read-only)

inventory_batches[].​idintegerrequired

Hive unique ID for the batch (read-only)

inventory_batches[].​namestringrequired

Name of the batch (read-only)

inventory_batches[].​stocked_quantitiesArray of objects(SkuInventoryBatchQuantityPerWarehouse)required

Inventory per warehouse for this batch (see SkuInventoryBatchQuantityPerWarehouse) (read-only)

inventory_batches[].​stocked_quantities[].​stockedinteger>= 0required

Quantity in the warehouse for this batch in this warehouse

inventory_batches[].​stocked_quantities[].​warehouse_idintegerrequired

Hive's unique warehouse ID

inventory_batches[].​tracking_codestringrequired

Tracking code (read-only)

inventory_per_warehouseArray of objects(SkuInventoryPerWarehouse)required

Current inventory per warehouse

inventory_per_warehouse[].​availableintegerrequired

Quantity available for sale (stocked minus reserved)

inventory_per_warehouse[].​reservedinteger>= 0required

Quantity reserved/committed for orders

inventory_per_warehouse[].​stockedinteger>= 0required

Quantity in the warehouse (available plus reserved)

inventory_per_warehouse[].​warehouse_idintegerrequired

Hive's unique warehouse ID

namestringrequired

Name of this SKU

sku_codestringrequired

SKU code - visible in the UI

statusstring(SkuStatus)required
Enum"active""deleted"
un_numbersArray of stringsrequired

Dangerous good UN Numbers

weight_in_kgnumber or null>= 0required
Any of:

Weight of SKU in kilograms

>= 0
number>= 0
Response
application/json
{
  "id": 1001,
  "name": "T-Shirt Black M",
  "sku_code": "SKU-001",
  "barcode": "1234567890123",
  "batch_tracking_enabled": false,
  "cost_in_cents": 800,
  "country_code_of_origin": "DE",
  "created_at": "2023-09-01T08:00:00Z",
  "updated_at": "2023-10-01T14:30:00Z",
  "dangerous_good": false,
  "fulfilled_by": "hive",
  "h_codes": [],
  "hazardous_good": false,
  "hs_code": "610910",
  "image_url": "https://cdn.hive.app/skus/sku-001.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA4%&X-Amz-Date=20230525T083045Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=d8e3",
  "inventory": {
    "available": 90,
    "reserved": 10,
    "stocked": 100
  },
  "inventory_batches": [],
  "inventory_per_warehouse": [
    { … }
  ],
  "status": "active",
  "un_numbers": [],
  "weight_in_kg": 0.2
}

Get a SKU by merchant SKU code

Request

Returns a specific SKU using the merchant's SKU code.

Security
BearerAuth
Query
sku_codestringnon-emptyrequired
curl -i -X GET \
  'https://hive-merchant-api.redocly.app/_mock/merchant-api-v2/mapi_v2_oas31/skus/by_sku_code?sku_code=string' \
  -H 'Authorization: Bearer <YOUR_token_HERE>'

Responses

A SKU

Bodyapplication/json
barcodestring or nullnon-empty

Barcode of the SKU

batch_tracking_enabledbooleanrequired

Whether batch tracking of this SKU is enabled

cost_in_centsinteger or null>= 0

Cost in cents (currency of the shop is implied)

country_code_of_originstring or null^[A-Z]{2}$

2-letter ISO 3166-1 code of country of origin

created_atstring(date-time)read-onlyrequired

When this SKU was created

updated_atstring(date-time)read-onlyrequired

When this SKU was last updated

dangerous_goodbooleanrequired

Sku is a dangerous good

fulfilled_bystring(SkuFulfilledBy)required
Enum"hive""new""other"
h_codesArray of stringsrequired

Hazardous good H Codes

hazardous_goodbooleanrequired

SKU is a hazardous good

hs_codestring or null

The general Harmonized System (HS) code for the SKU

idinteger(int64)read-onlyrequired

Hive unique identifier for this SKU

image_urlstring or null

Publicly accessible URL of an image for this SKU

inventoryobject(SkuInventory)required
inventory.​availableintegerrequired

Quantity available for sale (stocked minus reserved)

inventory.​reservedinteger>= 0required

Quantity reserved/committed for orders

inventory.​stockedinteger>= 0required

Quantity in the warehouse (available plus reserved)

inventory_batchesArray of objects(SkuInventoryBatch)required

Current inventory per batch

inventory_batches[].​expiry_datestring or null(date)required

Expiration date of the batch (ISO8601 date, read-only)

inventory_batches[].​idintegerrequired

Hive unique ID for the batch (read-only)

inventory_batches[].​namestringrequired

Name of the batch (read-only)

inventory_batches[].​stocked_quantitiesArray of objects(SkuInventoryBatchQuantityPerWarehouse)required

Inventory per warehouse for this batch (see SkuInventoryBatchQuantityPerWarehouse) (read-only)

inventory_batches[].​stocked_quantities[].​stockedinteger>= 0required

Quantity in the warehouse for this batch in this warehouse

inventory_batches[].​stocked_quantities[].​warehouse_idintegerrequired

Hive's unique warehouse ID

inventory_batches[].​tracking_codestringrequired

Tracking code (read-only)

inventory_per_warehouseArray of objects(SkuInventoryPerWarehouse)required

Current inventory per warehouse

inventory_per_warehouse[].​availableintegerrequired

Quantity available for sale (stocked minus reserved)

inventory_per_warehouse[].​reservedinteger>= 0required

Quantity reserved/committed for orders

inventory_per_warehouse[].​stockedinteger>= 0required

Quantity in the warehouse (available plus reserved)

inventory_per_warehouse[].​warehouse_idintegerrequired

Hive's unique warehouse ID

namestringrequired

Name of this SKU

sku_codestringrequired

SKU code - visible in the UI

statusstring(SkuStatus)required
Enum"active""deleted"
un_numbersArray of stringsrequired

Dangerous good UN Numbers

weight_in_kgnumber or null>= 0required
Any of:

Weight of SKU in kilograms

>= 0
number>= 0
Response
application/json
{
  "id": 1001,
  "name": "T-Shirt Black M",
  "sku_code": "SKU-001",
  "barcode": "1234567890123",
  "batch_tracking_enabled": false,
  "cost_in_cents": 800,
  "country_code_of_origin": "DE",
  "created_at": "2023-09-01T08:00:00Z",
  "updated_at": "2023-10-01T14:30:00Z",
  "dangerous_good": false,
  "fulfilled_by": "hive",
  "h_codes": [],
  "hazardous_good": false,
  "hs_code": "610910",
  "image_url": "https://cdn.hive.app/skus/sku-001.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA4%&X-Amz-Date=20230525T083045Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=d8e3",
  "inventory": {
    "available": 90,
    "reserved": 10,
    "stocked": 100
  },
  "inventory_batches": [],
  "inventory_per_warehouse": [
    { … }
  ],
  "status": "active",
  "un_numbers": [],
  "weight_in_kg": 0.2
}

Partially update a SKU by merchant SKU code

Request

Partially updates a SKU using the merchant's SKU code.

Security
BearerAuth
Query
sku_codestringnon-emptyrequired
Bodyapplication/json
barcodestring or nullnon-empty

The SKU barcode

batch_tracking_enabledboolean

Enables inventory tracking per batch (defaults to false if omitted)

cost_in_centsinteger or null>= 0

The cost (not price) of this SKU

country_code_of_originstring or null^[A-Z]{2}$

2-letter ISO 3166-1 code of country of origin

hs_codestring or null

Harmonized System code

image_urlstring or null

Image of the product, must be publicly accessible.

namestringnon-empty

A human-readable name or title

sku_codestringnon-empty

An ID that uniquely identifies this SKU

weight_in_kgnumber or null>= 0
Any of:

Weight in kilograms

>= 0
number>= 0
curl -i -X PATCH \
  'https://hive-merchant-api.redocly.app/_mock/merchant-api-v2/mapi_v2_oas31/skus/by_sku_code?sku_code=string' \
  -H 'Authorization: Bearer <YOUR_token_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "T-Shirt Black M",
    "sku_code": "SKU-001",
    "barcode": "1234567890123",
    "batch_tracking_enabled": false,
    "cost_in_cents": 800,
    "country_code_of_origin": "DE",
    "hs_code": "610910",
    "image_url": "https://cdn.hive.app/skus/sku-001.jpg",
    "weight_in_kg": 0.2
  }'

Responses

SKU updated successfully

Bodyapplication/json
barcodestring or nullnon-empty

Barcode of the SKU

batch_tracking_enabledbooleanrequired

Whether batch tracking of this SKU is enabled

cost_in_centsinteger or null>= 0

Cost in cents (currency of the shop is implied)

country_code_of_originstring or null^[A-Z]{2}$

2-letter ISO 3166-1 code of country of origin

created_atstring(date-time)read-onlyrequired

When this SKU was created

updated_atstring(date-time)read-onlyrequired

When this SKU was last updated

dangerous_goodbooleanrequired

Sku is a dangerous good

fulfilled_bystring(SkuFulfilledBy)required
Enum"hive""new""other"
h_codesArray of stringsrequired

Hazardous good H Codes

hazardous_goodbooleanrequired

SKU is a hazardous good

hs_codestring or null

The general Harmonized System (HS) code for the SKU

idinteger(int64)read-onlyrequired

Hive unique identifier for this SKU

image_urlstring or null

Publicly accessible URL of an image for this SKU

inventoryobject(SkuInventory)required
inventory.​availableintegerrequired

Quantity available for sale (stocked minus reserved)

inventory.​reservedinteger>= 0required

Quantity reserved/committed for orders

inventory.​stockedinteger>= 0required

Quantity in the warehouse (available plus reserved)

inventory_batchesArray of objects(SkuInventoryBatch)required

Current inventory per batch

inventory_batches[].​expiry_datestring or null(date)required

Expiration date of the batch (ISO8601 date, read-only)

inventory_batches[].​idintegerrequired

Hive unique ID for the batch (read-only)

inventory_batches[].​namestringrequired

Name of the batch (read-only)

inventory_batches[].​stocked_quantitiesArray of objects(SkuInventoryBatchQuantityPerWarehouse)required

Inventory per warehouse for this batch (see SkuInventoryBatchQuantityPerWarehouse) (read-only)

inventory_batches[].​stocked_quantities[].​stockedinteger>= 0required

Quantity in the warehouse for this batch in this warehouse

inventory_batches[].​stocked_quantities[].​warehouse_idintegerrequired

Hive's unique warehouse ID

inventory_batches[].​tracking_codestringrequired

Tracking code (read-only)

inventory_per_warehouseArray of objects(SkuInventoryPerWarehouse)required

Current inventory per warehouse

inventory_per_warehouse[].​availableintegerrequired

Quantity available for sale (stocked minus reserved)

inventory_per_warehouse[].​reservedinteger>= 0required

Quantity reserved/committed for orders

inventory_per_warehouse[].​stockedinteger>= 0required

Quantity in the warehouse (available plus reserved)

inventory_per_warehouse[].​warehouse_idintegerrequired

Hive's unique warehouse ID

namestringrequired

Name of this SKU

sku_codestringrequired

SKU code - visible in the UI

statusstring(SkuStatus)required
Enum"active""deleted"
un_numbersArray of stringsrequired

Dangerous good UN Numbers

weight_in_kgnumber or null>= 0required
Any of:

Weight of SKU in kilograms

>= 0
number>= 0
Response
application/json
{
  "id": 1001,
  "name": "T-Shirt Black M",
  "sku_code": "SKU-001",
  "barcode": "1234567890123",
  "batch_tracking_enabled": false,
  "cost_in_cents": 800,
  "country_code_of_origin": "DE",
  "created_at": "2023-09-01T08:00:00Z",
  "updated_at": "2023-10-01T14:30:00Z",
  "dangerous_good": false,
  "fulfilled_by": "hive",
  "h_codes": [],
  "hazardous_good": false,
  "hs_code": "610910",
  "image_url": "https://cdn.hive.app/skus/sku-001.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA4%&X-Amz-Date=20230525T083045Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=d8e3",
  "inventory": {
    "available": 90,
    "reserved": 10,
    "stocked": 100
  },
  "inventory_batches": [],
  "inventory_per_warehouse": [
    { … }
  ],
  "status": "active",
  "un_numbers": [],
  "weight_in_kg": 0.2
}

Delete a SKU by merchant SKU code

Request

Deletes a SKU using the merchant's SKU code.

Security
BearerAuth
Query
sku_codestringnon-emptyrequired
curl -i -X DELETE \
  'https://hive-merchant-api.redocly.app/_mock/merchant-api-v2/mapi_v2_oas31/skus/by_sku_code?sku_code=string' \
  -H 'Authorization: Bearer <YOUR_token_HERE>'

Responses

SKU deleted successfully

Response
No content

SalesChannels

Operations related to sales channels

Operations

Shipments

Operations related to shipments

OperationsWebhooks

Warehouses

Operations related to warehouses

Operations

Webhooks

Webhook event notifications

Webhooks