Skip to content

Create a kitting request

Request

Requests a kitting run: Hive assembles quantity kits in the given warehouse, exactly as when a kit is requested in the Hive app. Name the kit in one of two ways, never both:

  • kit_definition_id: an existing kit definition, from GET /kit_definitions or a kitting request returned by this API, to request the same kit again.
  • kit_definition: a new kit definition, created with the request, with the same fields and rules as POST /kit_definitions.

A body with both or neither is rejected with a 400. The new request starts in requested and waits for Hive's review. It is refused with a 422 when fulfillment is paused for the merchant, when the kit definition or the warehouse is not the merchant's, when the inline kit definition is refused for any reason POST /kit_definitions gives, or when production_date_required is true for a kit SKU without batch tracking; nothing is created then, not even the definition.

Security
BearerAuth
Bodyapplication/jsonrequired
One of:

Requests another run of an existing kit definition.

kit_definition_idinteger, (int64)required

The kit definition to assemble, from GET /kit_definitions or kit_definition_id of a kitting request; it must belong to one of the merchant's SKUs

production_date_requiredboolean

Whether the warehouse records a production date for the produced kits; may only be true when the kit SKU has batch tracking enabled

Default:false
quantityinteger, (int32), >= 1required

Number of kits to assemble

warehouse_idinteger, (int64)required

The warehouse that assembles the kits, one of the merchant's warehouses (see GET /warehouses)

curl -i -X POST \
  https://hive-merchant-api.redocly.app/_mock/merchant-api-v2/mapi_v2_oas31/kitting_requests \
  -H 'Authorization: Bearer <YOUR_token_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "kit_definition_id": 9311,
    "warehouse_id": 4,
    "quantity": 500
  }'

Responses

Kitting request created successfully

Bodyapplication/json
completed_atstring or null, (date-time)read-onlyrequired

When the produced kits were restocked and the request completed; null until then

componentsArray of objects(KittingRequestComponent)read-onlyrequired

The component SKUs one kit is assembled from, in the order of the kit definition

created_atstring, (date-time)read-onlyrequired

When the kitting request was created

idinteger, (int64)read-onlyrequired

Hive's unique identifier for this kitting request

kit_definition_idinteger, (int64)read-onlyrequired

The kit definition (components and assembly instructions) this request uses; pass it to POST /kitting_requests to request the same kit again

produced_quantityinteger or null, (int32)read-onlyrequired

Number of kits produced and restocked; null until the request is completed

production_date_requiredbooleanread-onlyrequired

Whether the warehouse records a production date for the produced kits (only for kit SKUs with batch tracking)

quantityinteger, (int32)read-onlyrequired

Number of kits requested

restocking_shipment_idinteger or null, (int64)read-onlyrequired

The restocking shipment, created with the request, that brings the produced kits back into stock and is readable through GET /restocking_shipments/{id}; null for requests created before November 2025

sku_codestring or nullread-onlyrequired

The merchant's SKU identifier of the kit SKU being produced

sku_idinteger, (int64)read-onlyrequired

Hive's SKU identifier of the kit SKU being produced

statusstring(KittingRequestStatus)read-onlyrequired

Status of the kitting request. Possible values:

  • requested: Created and waiting for Hive's review of the kit
  • approved: Reviewed by Hive and waiting for the components to be picked
  • processing: The components are being picked and assembled, or the kits are being restocked
  • completed: The produced kits are back in stock; produced_quantity holds their number
  • cancelled: The request was cancelled
Enum:"requested""approved""processing""completed""cancelled"
updated_atstring, (date-time)read-onlyrequired

When the kitting request was last updated

warehouse_idinteger, (int64)read-onlyrequired

The ID of the warehouse that assembles the kits

Response
{
  "id": 11842,
  "status": "completed",
  "quantity": 500,
  "produced_quantity": 498,
  "production_date_required": false,
  "warehouse_id": 4,
  "sku_id": 586004,
  "sku_code": "GIFTBOX-XMAS",
  "kit_definition_id": 9311,
  "components": [
    { … },
    { … }
  ],
  "restocking_shipment_id": 66241,
  "created_at": "2026-09-01T09:12:44.512+02:00",
  "updated_at": "2026-09-04T16:03:10.871+02:00",
  "completed_at": "2026-09-04T16:03:10.000+02:00"
}