Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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
The API responds with the following headers to indicate the number of requests used and the maximum available:
Any requests above the limit will be denied with a 429 response code (too many requests). In that case, the response also includes an extra header which shows how many seconds you need to wait before sending a new request:
If your API key is missing, or wrong, you'd get a 401 Unauthorized with this JSON response:
Another example, when the request is malformed, you'd get a 400 Bad request:
Finally, if the data is not valid, you'd get a 422 Unprocessable Entity:
When you create or update an object, you will get the final state of the object in the response:
When you get a collection of objects in the response, the response is an object with a data property and a pagination property. The actual collection of object is in the data property:
The pagination.page_count property of the response, returns how many pages are available. If no page parameter is provided, it defaults to 1 (that is, the first page of results).
Dive into the specifics of each API endpoint by checking out our complete documentation.
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 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:
List of API changes by date
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
2023-05-29
2023-05-18
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
Add GET /warehouses endpoint
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
To protect our servers from getting overloaded and avoid misuse, we enforce a rate limit of 100 requests per minute. You shouldn't need to poll frequently for status updates as you can get real-time updates via . In case you have a valid use case for a higher rate limit, please contact your account manager.
When a request is unsuccessful, you will get an HTTP status code of or . The body then will always contain an errors property which contains an array of human-readable errors.
When an API request is successful, you will get an HTTP status code of . The response body will either be a single object or a collection of objects.
In order to access all the objects of the collection, you need to send multiple requests to an endpoint. This works by adding the query string parameter page to the URL (e.g. )
The production domain for the HIVE API is , the staging domain is
for VS code
for the command line
Add barcode to the resource.
Add production and staging domains in the page.
Add batch inventory information to the resource.
city
String (read-only)
City where the warehouse is located
country
String (read-only)
id
Integer (read-only)
Hive unique ID
name
String (read-only)
Name of the warehouse
GET https://app.hive.app/merchant_api/v1/warehouses
Returns all merchant's warehouses.
Country 2-letter code where the warehouse is located
carrier
String
Carrier name
completed_handling_at
ISO8601 datetime
When the return handling finished
created_at
ISO8601 datetime
When the return was created
id
Integer
Hive's unique identifier
order
Details of the associated order
photos
Photos of the returned items
received_at
ISO8601 datetime
When the return was received
return_items
List of items announced by the customer (via the Customer Portal). Can be empty if the return is not a Customer Portal return.
return_line_items
List of items that were actually handled in the FC. Can be empty if return items have not been handled in the FC yet.
return_reason
String
Possible values:
customer_return
not_picked_up
invalid_address
rejected_by_customer
customs_documents_missing
other
null or empty string
return_reason_type
String
Possible values: active - customer return (the end-customer actively shipped the return)
passive - carrier return (the end-customer never touched the parcel - it was shipped back by the carrier for reasons such as invalid address, the customer didn’t pick up their parcel from the shop or requested that it be sent back before receiving it, damages, customs documents missing, etc.)
null or empty string - this happens in the rare case that a return is created before it’s processed and it is not a Customer Portal return, all Customer Portal returns are "active"
started_processing_at
ISO8601 datetime
When processing at the fulfillment center started
status
String
Possible values: on_the_way - is on the way to a fulfillment center
arrived - arrived to a fulfillment center
processing - the return processing is in progress
action_required - waiting for merchant guidance
handling_completed - the return processing is in completed
tracking_code
String
Tracking number assigned by the carrier
tracking_url
String
Carrier website showing tracking information
customer_return_message
String
Reason details provided by the customer
customer_return_reason
String
Reason provided by the customer
id
Integer
Hive's unique identifier
quantity
Integer
Quantity of items announced
sku
SKU details of the item
condition
String
Possible values: A - Unused and in original packaging. B - Unused with missing/damaged packaging. C - Product is used or damaged.
follow_up_action
String
Action to be performed on the returned item. Possible values: restock, dispose and send_back Those actions are pre-selected based on return rules (Hive account manager inserts return rules into the system after negotiation with a merchant).
id
Integer
Hive's unique identifier
inventory_batch_id
Integer
Unique identifier in Hive system of the inventory batch (if present) into which returned item is going to be restocked (relevant only when "follow_up_action": "restock")
photos
Photos of the returned item
return_item_id
Integer
Announced return item's unique identifier in Hive system (can be blank, e.g. when the return is not a Customer Portal return)
sku
SKU details of the item
quantity
Integer
The quantity of items returned for the same SKU
id
Integer
Hive's unique SKU identifier
merchant_sku_id
String
Merchant's unique SKU identifier
id
Integer
Hive's unique order identifier
merchant_order_id
String
Merchant's unique order identifier
name
String
Customer's order identifier
id
Integer
Hive's unique identifier
image_url
String
Publicly accessible URL (for 15 minutes)
photo_type
String
Type of photo. Usual values: inside or outside
id
Integer
Hive's unique identifier
image_url
String
Publicly accessible URL (for 15 minutes)
GET https://app.hive.app/merchant_api/v1/returns
Returns paginated order returns ordered by descending creation time.
created_at[lt]
ISO8601 datetime
Return results where the created_at field is less than this value.
created_at[lte]
ISO8601 datetime
Return results where the created_at field is less than or equal to this value.
created_at[gt]
ISO8601 datetime
Return results where the created_at field is greater than this value.
created_at[gte]
ISO8601 datetime
Return results where the created_at field is greater than or equal to this value.
GET https://app.hive.app/merchant_api/v1/returns/{id}
Returns specific order return belonging to the merchant and with matching Hive ID
id*
Integer
The (Hive) ID of the return
A object
An array of objects
An array of objects
An array of objects
A object
Array of objects
A object
barcode
String (read-only)
The barcode of the shipment
delivery_option*
String
One of the following: postal, courier, dropoff, hive_freight
estimated_arrival_date*
ISO8601 date
Estimated arrival date
id
Integer (read-only)
Hive's unique identifier
po_number
String
Purchase order number
restocking_shipment_items
A list of items in the shipment
status
String (read-only)
Possible values:
shipped - initial status meaning that restocking shipment is on the way
delivered - the restocking shipment is delivered to the fulfillment center, but its content is not verified yet
arrived - Hive completed the arrival documentation, checked packing slip, picture of shipment and documents are uploaded
processing - the restocking shipment is getting unpacked and its items are getting restocked into storage boxes and pallets
restocked - the restocking shipment is fully processed in the fulfillment center and its items are completely restocked
cancelled - the restocking shipment is cancelled by merchant
supplier_name
String
Supplier name
tracking_code
String
Shipment tracking code
warehouse_id*
Integer
The ID of the Hive destination warehouse
announced_quantity
Integer
Quantity of this item in the shipment
arrived_quantity
Integer (read-only)
Arrived quantity of this item (after shipment is received)
damaged_quantity
Integer (read-only)
Damaged quantity of this item (after shipment is received)
id
Integer (read-only)
Hive's unique identifier
inventory_batches
A RestockingShipmentInventoryBatch object
Batches of this item included in the shipment
missing_quantity
Integer (read-only)
Missing quantity of this item (after shipment is received)
remarks
String
Free text for remarks
sku_id*
Integer
Hive SKU identifier
total_cost_in_cents
Integer
Cost in cents
arrived_quantity
Integer (read-only)
Arrived quantity of this batch (after shipment is received)
expiry_date
ISO8601 date (read-only)
Expiration date of the batch
id
Integer (read-only)
Hive's unique identifier
name
String (read-only)
Batch name
tracking_code
String (read-only)
Batch tracking code
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 https://app.hive.app/merchant_api/v1/restocking_shipments/{id}
id*
String
The (Hive) ID of the restocking shipment
POST https://app.hive.app/merchant_api/v1/restocking_shipments/
warehouse_id*
Integer
An ID that uniquely identifies the warehouse
estimated_arrival_date*
ISO8601 datetime
The estimated arrival date
delivery_option*
String
The delivery option, must be one of: postal, courier, dropoff, hive_freight
tracking_code
String
The shipment tracking code
po_number
String
The po number
supplier_name
String
The supplier name
restocking_shipment_items.sku_id*
Integer
The (Hive) ID of the sku
restocking_shipment_items.announced_quantity*
Integer
The sku quantity
restocking_shipment_items.remarks
String
The remarks
restocking_shipment_items.total_cost_in_cents
Integer
The total cost in cents of the
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
id*
Integer
The (Hive) ID of the restocking shipment
warehouse_id*
Integer
An ID that uniquely identifies the wharehouse
estimated_arrival_date*
ISO8601 datetime
The estimated arrival date
delivery_option*
String
The delivery option, must be one of: postal, courier, dropoff, hive_freight
tracking_code
String
The shipment tracking code
po_number
String
The po number
supplier_name
String
The supplier name
restocking_shipment_items.sku_id*
Integer
The (Hive) ID of the sku
restocking_shipment_items.announced_quantity*
Integer
The sku quantity
restocking_shipment_items.remarks
String
The remarks
restocking_shipment_items.total_cost_in_cents
Integer
The total cost in cents of the
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
id*
Integer
The (Hive) ID of the restocking shipment
GET https://app.hive.app/merchant_api/v1/skus
Returns SKUs ordered by descending creation time.
POST https://app.hive.app/merchant_api/v1/skus
PATCH https://app.hive.app/merchant_api/v1/skus/{id}
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.
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.
An array of objects
reserved
Integer (read-only)
Quantity reserved for orders
stocked
Integer (read-only)
Available for sale (minus any buffer quantity, if configured)
total
Integer (read-only)
Available (will be equal to stocked if buffer is 0)
reserved
Integer (read-only)
Quantity reserved for orders
stocked
Integer (read-only)
Available for sale (minus any buffer quantity, if configured)
total
Integer (read-only)
Available (will be equal to stocked if buffer is 0)
warehouse_id
Integer (read-only)
Hive's unique warehouse ID
quantity
Integer (read-only)
Available for sale
warehouse_id
Integer (read-only)
Hive's unique warehouse ID
merchant_sku_ids[]
String[]
Allow to filters skus by merchant_sku_id
created_at[lt]
ISO8601 datetime
Return results where the created_at field is less than this value.
created_at[lte]
ISO8601 datetime
Return results where the created_at field is less than or equal to this value.
created_at[gt]
ISO8601 datetime
Return results where the created_at field is greater than this value.
created_at[gte]
ISO8601 datetime
Return results where the created_at field is greater than or equal to this value.
id*
Integer
The (Hive) ID of the SKU to update
skus*
Object[]
List of SKUs for upsert
id*
Integer
The (Hive) ID of the SKU to delete
barcode
String
Barcode of the SKU
batch_tracking_enabled
Boolean
Whether batch tracking of this SKU is enabled
cost_in_cents
Integer
Cost in cents (currency of the shop is implied)
country_code_of_origin
String
created_at
ISO8601 datetime (read-only)
When this SKU was created
dangerous_good
Boolean
Sku is a dangerous good
fulfilled_by
String (read-only)
Who is fulfilling this SKU. Valid values: hive, other, new
h_codes
Array of String
Hazardous good H Codes
hazardous_good
Boolean
Sku is a hazardous good
hs_code
String
id
Integer (read-only)
Hive unique identifier for this SKU
image_url
String
Publicly accessible URL of an image for this SKU
inventory
Current inventory
inventory_batches
Current inventory per batch
inventory_per_warehouse
Current inventory per warehouse
merchant_sku_id*
String
SKU code as provided by the merchant
name*
String
Name of this SKU
un_names
Array of String
Dangerous good UN Numbers
status
String (read-only)
Valid values: active, deleted
weight_in_kg
Float
Weight of SKU in kilograms
expiry_date
ISO8601 date (read-only)
Expiration date of the batch
id
Integer (read-only)
Hive unique ID for the batch
name
String (read-only)
Name of the batch
stocked_quantities
Available for sale per warehouse
tracking_code
String (read-only)
Tracking code
name*
String
A human-readable name or title
merchant_sku_id*
String
An ID that uniquely identifies this SKU
cost_in_cents
Integer
The cost (not price) of this SKU
country_code_of_origin
String
hs_code
String
weight_in_kg
Float
Weight in kilograms
image_url
String
Image of the product, must be publicly accessible.
barcode
String
The SKU barcode
batch_tracking_enabled
Boolean
Enables inventory tracking per batch (defaults to false if omitted)
merchant_sku_id
String
An ID that uniquely identifies this SKU
name
String
A human-readable name or title
cost_in_cents
Integer
The cost (not price) of this SKU
country_code_of_origin
String
hs_code
String
weight_in_kg
Float
Weight in kilograms
image_url
String
Image of the product, must be publicly accessible.
barcode
String
The SKU barcode
batch_tracking_enabled
Boolean
Enables inventory tracking per batch
carrier_preference
String
The preferred carrier to use for delivering this order
created_at
ISO8601 datetime
When the order was created. Will default to current time if omitted.
currency
String
custom_metadata
JSON object
A JSON object with custom metadata
customer_order_number
String
The order number which your customer sees. In case this is not the same as merchant_order_id.
financial_status
String
Financial status of this order, can be one of the following: paid, refunded, pending, failed
id
Integer (read-only)
Hive's unique identifier for this order
items*
An array of OrderLineItem objects
A collection of order items
merchant_order_id*
String
An ID that uniquely identifies this order
payment_method
String
The payment method used for this order
shipping_address*
An Address object
The shipping address
status
String (read-only)
Order status. Possible values:
fulfillable - will be fulfilled by Hive, normally all orders created via Merchant API are treated as fulfillable by default
unfulfillable - will not be fulfilled by Hive; such a status could be assigned to an order for example when shipping address's country is among blacklisted countries (configured on Hive side by Account Manager) for that shop; also order will have this status after cancellation
fulfilled - order is fulfilled
tags
An array of Strings
String tags for this order
total_net_refunds_in_cents
Integer
Net refunds in cents (total refunded minus taxes)
total_net_revenue_in_cents
Integer
Net revenue in cents (amount paid minus taxes)
total_price_in_cents
Integer
Total price paid in cents
total_tax_in_cents
Integer
Total tax paid in cents
total_tax_refunds_in_cents
Integer
Total tax in the refunded amount in cents
merchant_item_id*
String
Identifier for the line item. Needs to be unique among the line items of the order.
merchant_sku_id
String
The merchant's SKU identifier - required if sku_id is not provided
price_per_unit_in_cents*
Integer
The price per unit of this item
price_per_unit_in_cents_with_discount
Integer
The discounted price per unit of this item
quantity*
Integer
The quantity of this item in the order
sku_id
Integer
Hive's SKU identifier - required if merchant_sku_id is not provided
city*
String
City name
company
String
Company name
country_code*
String
String
Email address
first_name
String
Customer's first name - required if last_name is omitted
full_name*
String
Customer's full name
last_name
String
Customer's last name - required if first_name is omitted
line1*
String
Customer's address line 1
line2
String
Customer's address line 2
parcel_point_id
String
phone
String
Customer's phone number
postal_code*
String
Customer's postal code
province_or_state_code
String
GET https://app.hive.app/merchant_api/v1/orders
Returns orders ordered by descending creation time.
created_at[lt]
ISO8601 datetime
Return results where the created_at field is less than this value.
created_at[lte]
ISO8601 datetime
Return results where the created_at field is less than or equal to this value.
created_at[gt]
ISO8601 datetime
Return results where the created_at field is greater than this value.
created_at[gte]
ISO8601 datetime
Return results where the created_at field is greater than or equal to this value.
GET https://app.hive.app/merchant_api/v1/orders/{id}
id*
Integer
The (Hive) ID of the order
POST https://app.hive.app/merchant_api/v1/orders
merchant_order_id*
String
An ID that uniquely identifies this order
shipping_address*
Object
A shipping address
items*
[]Object
A collection of order items
customer_order_number
String
The order number which your customer sees. In case this is not the same as merchant_order_id.
carrier_preference
String
The preferred carrier to use for delivering this order
tags
[]String
An optional list of strings. Can be used to perform actions on the order (e.g. with add-on rules).
custom_metadata
Object
A JSON object with custom metadata
shipping_address.first_name
String
First name of recipient - either this, or last_name is required
shipping_address.last_name
String
Last name of recipient - either this, or first_name is required
shipping_address.line2
String
Destination address line 2 of shipment
shipping_address.line1*
String
Destination address line 1 of shipment
shipping_address.full_name*
String
Full name of recipient
shipping_address.city*
String
Destination city of shipment
shipping_address.postal_code*
String
Destination postal code of shipment
shipping_address.country_code*
String
Destination country code of shipment
shipping_address.company
String
Company name of recipient
shipping_address.phone
String
Phone number of recipient
shipping_address.email
String
Email of recipient
items[].quantity*
Integer
The quantity of this item in the order
items[].price_per_unit_in_cents*
Integer
The price per unit of this item
items[].merchant_item_id*
String
An unique identifier (in the scope of this order) for this item. Items are matched by this ID, when updating an order.
items[].sku_id
Integer
The (Hive) SKU ID for this item - required if merchant_sku_id is missing
items[].merchant_sku_id
String
The merchant SKU ID for this item - required if sku_id is missing
items[].price_per_unit_in_cents_with_discount
Integer
The discounted price per unit of this item
shipping_address.parcel_point_id
String
Parcel point ID - currently only Sendcloud parcel points are supported
payment_method
String
The payment method used for this order
financial_status
String
Financial status of this order, can be one of the following: paid, refunded, pending, failed
shipping_address.province_or_state_code
String
Destination province or state code of shipment
created_at
ISO8601 datetime
The creation date of this order
total_price_in_cents
Integer
Total price of the order, in cents.
total_net_revenue_in_cents
Integer
Total revenue of the order, tax excluded, in cents.
total_tax_in_cents
Integer
Total tax od the order, in cents.
total_net_refunds_in_cents
Integer
Total refunds of the order, tax excluded, in cents.
total_tax_refunds_in_cents
Integer
Total tax refunds of the order, in cents.
currency
String
PATCH https://app.hive.app/merchant_api/v1/orders/{id}
id*
Integer
The (Hive) ID of the order
merchant_order_id
String
An ID that uniquely identifies this order
shipping_address
Object
A shipping address
shipping_address.first_name
String
First name of recipient
shipping_address.last_name
String
Last name of recipient
items[].sku_id
Integer
The (Hive) SKU ID for this item
items[].merchant_item_id*
String
The unique identifier of the item to update
items
[]Object
A collection of order items to update
shipping_address.postal_code
String
Destination postal code of shipment
shipping_address.country_code
String
shipping_address.city
String
Destination city of shipment
shipping_address.line2
String
Destination address line 2 of shipment
shipping_address.line1
String
Destination address line 1 of shipment
shipping_address.company
String
Company name of recipient
shipping_address.phone
String
Phone number of recipient
shipping_address.email
String
Email of recipient
shipping_address.full_name
String
Full name of recipient
customer_order_number
String
The order number which your customer sees. In case this is not the same as merchant_order_id.
items[].price_per_unit_in_cents
Integer
The price per unit of this item
items[].quantity
Integer
The quantity of this item in the order
items[].merchant_sku_id
String
The merchant SKU ID for this item
tags
[]String
An optional list of strings. Can be used to perform actions on the order (e.g. with add-on rules).
custom_metadata
Object
A JSON object with custom metadata
carrier_preference
String
The preferred carrier to use for delivering this order
items[].price_per_unit_in_cents_with_discount
Integer
The discounted price per unit of this item
shipping_address.parcel_point_id
String
Parcel point ID - currently only Sendcloud parcel points are supported
payment_method
String
The payment method used for this order
financial_status
String
Financial status of this order, can be one of the following: paid, refunded, pending, failed Responses 201: Created
shipping_address.province_or_state_code
String
Destination province or state code of shipment
created_at
ISO8601 datetime
The creation date of this order
total_price_in_cents
Integer
Total price of the order, in cents.
total_net_revenue_in_cents
Integer
Total revenue of the order, tax excluded, in cents.
total_tax_in_cents
Integer
Total tax od the order, in cents.
total_net_refunds_in_cents
Integer
Total refunds of the order, tax excluded, in cents.
total_tax_refunds_in_cents
Integer
Total tax refunds of the order, in cents. Responses 201: Created
currency
String
PUT https://app.hive.app/merchant_api/v1/orders/{id}/cancel
id*
Integer
created_at
ISO8601 datetime
When the shipment was created
delivered_at
ISO8601 datetime
When the shipment was delivered
delivery_status
String
Information transmitted to the carrier - the shipment has been marked as shipped by Hive but no further statuses from the carrier yet
In transit - the parcel is on the way to the carrier hub
Out for delivery - the parcel has left the carrier hub and is in the process of being delivered
Delivered - the parcel has been successfully delivered
Returned to sender - the carrier initiated a return to the sender
Action required - the parcel is going through an unconventional event (e.g. failed delivery attempt, shipment lost, address issues etc.)
id
Integer
The shipment's unique identifier in Hive
items
Which line items this shipment includes
merchant_order_id
String
Related order's unique identifier provided by merchant
order_id
Integer
Related order's unique identifier in Hive
shipment_provider
String
Name of the shipment provider/carrier
shipped_at
ISO8601 datetime
When the shipment was shipped
status
String
waiting_for_picking - initial status (normally shipment is created with this status during order import)
on_hold - shipment is on hold for now, for example because shop is configured to start fulfillment in future or there are some issues (e.g. incorrect address or not enough inventory amount)
picking_assigned - fulfillment center employee assigned themselves to pick this shipment's items
in_picking - shipment items picking process has been started
picked - shipment items have been picked and are ready for packing
in_packing - shipment items packing process has been started
packed - shipment items have been packed and are ready for shipping
in_shipping - shipping process has been started
shipped - a shipping label has been created for the shipment and it has left the packing station (and now the shipment is awaiting carrier pickup or is already picked up)
cancelled - shipment is cancelled and will not be fulfilled, e.g. because the order was cancelled via Merchant API
tracking_number
String
Tracking number assigned by the shipment provider/carrier
tracking_url
String
Shipment provider website showing tracking information
updated_at
ISO8601 datetime
When the shipment was updated
batches
Which batches were sent for this line item
id
Integer
The shipment item's unique identifier in Hive
merchant_item_id
String
The order line item identifier as provided by the merchant. Will be nullfor items added later (e.g. via add-on rules).
quantity
Integer
Number of SKUs in this line item
serial_numbers
Which serial numbers were sent for this line item
sku
SKU identifiers of this line item
expiry_date
ISO8601 date
Expiration date of the batch
name
String
Name of the batch
quantity
Integer
Number of items taken from this batch
tracking_code
String
Tracking code of the batch
serial_number
String
The serial number
id
Integer
Hive unique identifier for the SKU
merchant_sku_id
String
SKU identifier as provided by the merchant
GET https://app.hive.app/merchant_api/v1/shipments
Returns shipments ordered by descending creation time.
order_id
Integer
The (Hive) ID of the order
created_at[lt]
ISO8601 datetime
Return results where the created_at field is less than this value.
created_at[lte]
ISO8601 datetime
Return results where the created_at field is less than or equal to this value.
created_at[gt]
ISO8601 datetime
Return results where the created_at field is greater than this value.
created_at[gte]
ISO8601 datetime
Return results where the created_at field is greater than or equal to this value.
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).
Feeling like an eager beaver? Jump in to the quick start docs and get making your first request:
Dive a little deeper and start exploring our API reference to get an idea of everything that's possible with the API:
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:
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:
2-letter code of country of origin
The general (HS) code for the SKU
A object (read-only)
Array of object (read-only)
Array of object (read-only)
A object (read-only)
2-letter code of country of origin
code
2-letter code of country of origin
code
The international 3-letter code as defined by the , defaults to "EUR" if not provided
2-letter code of country
Parcel point ID - see
2-letter code of province/state code
The international 3-letter code as defined by the , defaults to "EUR" if not provided
Destination country code of shipment in
The international 3-letter code as defined by the , defaults to "EUR" if not provided
Array of objects
Array of objects
Array of objects
If your platform of choice is listed in you don't need to use this API.
delivery_status_updated
The delivery status of a shipment has changed
shipment_status_updated
The status of a shipment has changed
restocking_shipment_status_updated
The delivery status of a restocking shipment has changed
return_status_updated
The delivery status of a return has changed