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/

Inventory

Operations related to inventory

Operations

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

Warehouses

Operations related to warehouses

Operations

Webhooks

Webhook event notifications

Webhooks

orderStatusUpdatedWebhookWebhook

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

Unique identifier for this webhook event

timestampstring(date-time)required

When the event occurred

dataobject(Order)required
data.​carrier_preferencestring or nullrequired

The preferred carrier to use for delivering this order

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

When the order was created. Will default to current time if omitted.

data.​currencystring(CurrencyCode)^[A-Z]{3}$required

3-letter ISO 4217 currency code. Examples: EUR, USD, GBP, JPY

data.​custom_metadataobject or null

A JSON object with custom metadata

data.​customer_order_numberstring or null

The order number which your customer sees. In case this is not the same as merchant_order_id.

data.​external_created_atstring or null(date-time)

When the order was originally created/placed by the customer. This can be different from created_at when doing bulk imports or when there's a delay between order placement and API submission.

data.​financial_statusstring(OrderFinancialStatus)required

Financial status of this order. Possible values:

  • failed: Payment failed
  • paid: Payment completed successfully
  • pending: Payment is pending
  • refunded: Payment has been refunded
Enum"failed""paid""pending""refunded"
data.​idinteger(int64)read-onlyrequired

Hive's unique identifier for this order

data.​itemsArray of OrderItem (object)(OrderItem)required

List of items in the order (see OrderItem)

Any of:
data.​items[].​merchant_item_idstringrequired

Identifier for the line item. Needs to be unique among the line items of the order.

data.​items[].​price_per_unit_in_centsinteger(int32)>= 0

The price per unit of this item

data.​items[].​price_per_unit_in_cents_with_discountinteger(int32)>= 0

The discounted price per unit of this item

data.​items[].​quantityinteger(int32)>= 1required

The quantity of this item in the order

data.​items[].​sku_codestring

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

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

Hive's SKU identifier - required if sku_code is not provided

data.​merchant_order_idstringrequired

An ID that uniquely identifies this order within the sales channel. Must be unique per sales channel.

data.​payment_methodstring or null

The payment method used for this order

data.​sales_channel_idinteger(int64)required

The ID of the sales channel this order belongs to

data.​shipping_addressAddress (object)(Address)required
Any of:
data.​shipping_address.​citystringnon-emptyrequired

City name

data.​shipping_address.​companystring or null

Company name

data.​shipping_address.​country_codestring(CountryCode)^[A-Z]{2}$required

2-letter ISO 3166-1 country code. Examples: DE, US, FR, NL

data.​shipping_address.​emailstring or null(email)

Email address

data.​shipping_address.​first_namestring or nullnon-emptyrequired

Customer's first name - required if last_name and full_name are omitted

data.​shipping_address.​full_namestring or nullnon-empty

Customer's full name - required if first_name and last_name are omitted

data.​shipping_address.​last_namestring or nullnon-empty

Customer's last name - required if first_name and full_name are omitted

data.​shipping_address.​line1stringnon-emptyrequired

Customer's address line 1

data.​shipping_address.​line2string or null

Customer's address line 2

data.​shipping_address.​parcel_point_idstring or null

Parcel point ID - see Sendcloud service points

data.​shipping_address.​phonestring or null

Customer's phone number

data.​shipping_address.​postal_codestringnon-emptyrequired

Customer's postal code

data.​shipping_address.​province_or_state_codestring or null

State or province code. For US addresses, this should be the 2-letter state code (e.g., CA, NY, TX). For other countries, this should be the appropriate province/state/region code. Examples: CA (California), NY (New York), ON (Ontario), BE (Berlin)

data.​fulfillment_statusstring(OrderFulfillmentStatus)read-onlyrequired

Current fulfillment status of the order within Hive's fulfillment process. This tracks the order's progress from confirmation through delivery. Possible values:

  • waiting_for_picking: Order is confirmed and waiting to be picked in the fulfillment center
  • processing: Order is actively being processed (picked/packed) in the fulfillment center
  • partially_shipped: Some items from the order have been shipped, but others are still pending
  • shipped: All items from the order have been shipped
  • on_hold: Order is temporarily paused (e.g., payment issues, merchant request)
  • payment_pending: Order is waiting for payment confirmation
  • cancelled: Order has been cancelled
  • ignored: Order will not be fulfilled (automatically set based on external conditions)

Note: This field is read-only and managed entirely by Hive based on the fulfillment process.

Enum"waiting_for_picking""processing""partially_shipped""shipped""on_hold""payment_pending""cancelled""ignored"
data.​tagsArray of strings or null

String tags for this order

data.​total_net_refunds_in_centsinteger(int32)>= 0required

Net refunds in cents (total refunded minus taxes)

data.​total_net_revenue_in_centsinteger(int32)>= 0required

Net revenue in cents (amount paid minus taxes)

data.​total_price_in_centsinteger(int32)>= 0required

Total price paid in cents

data.​total_tax_in_centsinteger(int32)>= 0required

Total tax paid in cents

data.​total_tax_refunds_in_centsinteger(int32)>= 0required

Total tax in the refunded amount in cents

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

When the order was last updated

application/json
{
  "event_type": "order.status_updated",
  "event_id": "123e4567-e89b-12d3-a456-426614174000",
  "timestamp": "2023-10-01T12:00:00Z",
  "data": {
    "id": 123456,
    "merchant_order_id": "ORD-1001",
    "sales_channel_id": 10,
    "fulfillment_status": "shipped",
    "financial_status": "paid",
    "created_at": "2023-10-01T12:00:00Z",
    "currency": "EUR",
    "total_price_in_cents": 3000,
    "total_net_refunds_in_cents": 0,
    "total_net_revenue_in_cents": 2430,
    "total_tax_in_cents": 570,
    "total_tax_refunds_in_cents": 0,
    "carrier_preference": "DHL",
    "updated_at": "2023-10-01T14:30:00Z",
    "items": [ … ],
    "shipping_address": { … }
  }
}

Responses

Webhook received successfully

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

Status of the shipment. Possible values:

  • cancelled: Shipment cancelled and will not be fulfilled
  • in_packing: Packing process started
  • in_picking: Picking process started
  • in_shipping: Shipping process started
  • on_hold: On hold (e.g. future fulfillment, address issues, insufficient inventory)
  • packed: Items packed and ready for shipping
  • picked: Items picked and ready for packing
  • picking_assigned: Employee assigned to pick items
  • shipped: Shipping label created and left packing station
  • waiting_for_picking: Initial status, awaiting picking
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

Status of the shipment. Possible values:

  • cancelled: Shipment cancelled and will not be fulfilled
  • in_packing: Packing process started
  • in_picking: Picking process started
  • in_shipping: Shipping process started
  • on_hold: On hold (e.g. future fulfillment, address issues, insufficient inventory)
  • packed: Items packed and ready for shipping
  • picked: Items picked and ready for packing
  • picking_assigned: Employee assigned to pick items
  • shipped: Shipping label created and left packing station
  • waiting_for_picking: Initial status, awaiting picking
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

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)

Delivery option for the restocking shipment. Possible values:

  • courier: Delivered by courier service
  • dropoff: Dropped off at designated location
  • hive_freight: Delivered using Hive freight service
  • postal: Delivered via postal service
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

Restocking shipment status. Possible values:

  • arrived: Hive completed the arrival documentation, checked packing slip, picture of shipment and documents are uploaded
  • cancelled: the restocking shipment is cancelled by merchant
  • created: the restocking shipment is created and not yet shipped
  • processing: the restocking shipment is getting unpacked and its items are getting restocked into storage boxes and pallets
  • received: the restocking shipment is delivered to the fulfillment center, but its content is not verified yet
  • restocked: the restocking shipment is fully processed in the fulfillment center and its items are completely restocked
  • shipped: initial status meaning that restocking shipment is on the way
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

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

SKU details for a returned item

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

Details of the associated order

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

Status of the return. Possible values:

  • action_required: Waiting for merchant guidance
  • arrived: Arrived at fulfillment center
  • handling_completed: Return processing completed
  • on_the_way: On the way to fulfillment center
  • processing: Return processing in progress
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

inventoryTransferOrderStatusUpdatedWebhookWebhook

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

Unique identifier for this webhook event

timestampstring(date-time)required

When the event occurred

dataobject(InventoryTransferOrder)required
data.​completed_atstring or null(date-time)read-only

When the inventory transfer order was completed

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

When the inventory transfer order was created

data.​destination_idinteger(int64)required

The ID of the destination warehouse

data.​documentsArray of objects(InventoryTransferOrderDocument)required

List of documents associated with the inventory transfer order

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

Document ID

data.​documents[].​namestring or nullrequired

Document name

data.​documents[].​urlstringrequired

Document URL

data.​idinteger(int64)read-onlyrequired

Hive's unique identifier for this inventory transfer order

data.​itemsArray of objects(InventoryTransferOrderItem)required

List of items in the inventory transfer order

data.​items[].​idinteger(int64)read-onlyrequired

Hive's unique identifier for this item

data.​items[].​inventory_batchobject or null(InventoryTransferOrderInventoryBatch)
data.​items[].​quantityinteger(int32)>= 1required

The quantity of this item to transfer

data.​items[].​sku_codestringrequired

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

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

Hive's SKU identifier - required if sku_code is not provided

data.​orderobject or null(InventoryTransferOrderReference)required
data.​order.​idinteger or null(int64)

Order ID

data.​order.​statusstring or null

Order status

data.​order_notesstring or null

Notes for the inventory transfer order

data.​origin_idinteger(int64)required

The ID of the origin warehouse

data.​restocking_shipmentsArray of objects(InventoryTransferOrderRestockingShipment)required

List of restocking shipments associated with the inventory transfer order

data.​restocking_shipments[].​estimated_arrival_datestring or null(date)

Estimated arrival date

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

Restocking shipment ID

data.​restocking_shipments[].​itemsArray of objects(RestockingShipmentItem)required

Items in the restocking shipment

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

Quantity of this item in the shipment

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

Arrived quantity of this item (after shipment is received)

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

Damaged quantity of this item (after shipment is received)

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

Hive's unique identifier

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

Missing quantity of this item (after shipment is received)

data.​restocking_shipments[].​items[].​remarksstring or null

Free text for remarks

data.​restocking_shipments[].​items[].​sku_codestringrequired

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

data.​restocking_shipments[].​items[].​sku_idinteger(int64)required

Hive SKU identifier - required if sku_code is not provided

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

Cost in cents

data.​restocking_shipments[].​statusstringrequired

Restocking shipment status

data.​restocking_shipments[].​tracking_codestring or null

Tracking code

data.​restocking_shipments[].​tracking_urlstring or null

Tracking URL

data.​shipmentsArray of objects(InventoryTransferOrderShipment)required

List of shipments associated with the inventory transfer order

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

Shipment ID

data.​shipments[].​issuesArray of objectsrequired

Issues with the shipment

data.​shipments[].​itemsArray of objects(InventoryTransferOrderShipmentItem)required

Items in the shipment

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

Shipment item ID

data.​shipments[].​items[].​quantityinteger(int32)>= 1required

Quantity in the shipment

data.​shipments[].​items[].​sku_codestringrequired

The merchant's SKU code

data.​shipments[].​items[].​sku_idinteger(int64)required

The SKU ID

data.​shipments[].​restocking_shipmentobject(InventoryTransferOrderRestockingShipment)
data.​shipments[].​statusstringrequired

Shipment status

data.​statusstring(InventoryTransferOrderStatus)read-onlyrequired

Status of the inventory transfer order. Possible values:

  • pending: Initial status when the transfer order is created
  • created: The transfer order has been created and is ready for processing
  • processing: The transfer order is currently being processed
  • completed: The transfer order has been successfully completed
  • cancelled: The transfer order has been cancelled
Enum"pending""created""processing""completed""cancelled"
data.​updated_atstring(date-time)read-onlyrequired

When the inventory transfer order was last updated

application/json
{
  "event_type": "inventory_transfer_order.status_updated",
  "event_id": "123e4567-e89b-12d3-a456-426614174004",
  "timestamp": "2023-10-01T19:00:00Z",
  "data": {
    "id": 123456,
    "status": "completed",
    "created_at": "2023-10-01T19:00:00Z",
    "completed_at": "2023-10-01T20:00:00Z",
    "origin_id": 4,
    "destination_id": 2,
    "updated_at": "2023-10-01T20:00:00Z",
    "order": { … },
    "order_notes": "",
    "documents": [],
    "restocking_shipments": [],
    "shipments": [],
    "items": [ … ]
  }
}

Responses

Webhook received successfully