Skip to content

Create a kit definition

Request

Defines a new kit: the kit SKU it produces, its components with optional pinned inventory batches, and the assembly instructions, photos and video, as in the Hive app's kitting form. No kit is assembled until a kitting request names the definition; to define a kit and request it in one call, send the definition inline to POST /kitting_requests instead.

Photos are downloaded from the given URLs when the definition is created, so each URL must be publicly reachable. The definition is refused with a 422 when fulfillment is paused for the merchant, when the kit SKU or a component SKU is not the merchant's, when a component repeats the kit SKU or another component, when a pinned batch is not of its component's SKU, when a component's pinned batches do not add up to its quantity_per_kit, or when a photo cannot be downloaded.

Security
BearerAuth
Bodyapplication/jsonrequired
componentsArray of objects, non-empty(KitDefinitionComponentInput)required

The component SKUs one kit is assembled from, in assembly order; each SKU at most once, and never the kit SKU itself

instructionsstring, non-emptyrequired

Assembly instructions for the warehouse

namestring or null

Name of the kit definition; defaults to the kit SKU's name followed by a sequence number

photosArray of objects, <= 10 items(KitDefinitionPhotoInput)

Photos showing how the kit is assembled, downloaded from their URLs when the definition is created

sku_idinteger, (int64)required

Hive's SKU identifier of the kit SKU the definition produces; it must be one of the merchant's SKUs

video_urlstring or null

URL of a video showing how the kit is assembled; it must be an HTTP or HTTPS URL

curl -i -X POST \
  https://hive-merchant-api.redocly.app/_mock/merchant-api-v2/mapi_v2_oas31/kit_definitions \
  -H 'Authorization: Bearer <YOUR_token_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "sku_id": 586004,
    "instructions": "Place the tea at the bottom and the mug on top, then close the box with the ribbon.",
    "video_url": "https://videos.example.com/giftbox-assembly",
    "photos": [
      {
        "url": "https://images.example.com/giftbox-assembled.jpg"
      }
    ],
    "components": [
      {
        "sku_id": 161820,
        "quantity_per_kit": 2,
        "instructions": "Labels facing up",
        "inventory_batches": [
          {
            "inventory_batch_id": 123456,
            "quantity": 2
          }
        ]
      },
      {
        "sku_id": 161821,
        "quantity_per_kit": 1
      }
    ]
  }'

Responses

Kit definition created successfully

Bodyapplication/json
componentsArray of objects(KitDefinitionComponent)read-onlyrequired

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

created_atstring, (date-time)read-onlyrequired

When the kit definition was created

idinteger, (int64)read-onlyrequired

Hive's unique identifier for this kit definition; pass it as kit_definition_id to POST /kitting_requests

instructionsstring or nullread-onlyrequired

Assembly instructions for the warehouse

namestring or nullread-onlyrequired

Name of the kit definition; when none was given, the kit SKU's name followed by a sequence number

photosArray of objects(KitDefinitionPhoto)read-onlyrequired

Photos showing how the kit is assembled

sku_codestring or nullread-onlyrequired

The merchant's SKU identifier of the kit SKU the definition produces

sku_idinteger, (int64)read-onlyrequired

Hive's SKU identifier of the kit SKU the definition produces

updated_atstring, (date-time)read-onlyrequired

When the kit definition was last updated

video_urlstring or nullread-onlyrequired

URL of a video showing how the kit is assembled

Response
{
  "id": 9311,
  "name": "Christmas gift box 0003",
  "sku_id": 586004,
  "sku_code": "GIFTBOX-XMAS",
  "instructions": "Place the tea at the bottom and the mug on top, then close the box with the ribbon.",
  "video_url": "https://videos.example.com/giftbox-assembly",
  "components": [
    { … },
    { … }
  ],
  "photos": [
    { … }
  ],
  "created_at": "2026-09-01T09:12:44.512+02:00",
  "updated_at": "2026-09-01T09:12:44.512+02:00"
}