SKUs

The SKU resource

Property
Type
Description

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

fulfilled_by

String (read-only)

Who is fulfilling this SKU. Valid values: hive, other, new

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

status

String (read-only)

Valid values: active, deleted

weight_in_kg

Float

Weight of SKU in kilograms

*Required properties when creating a new record.

The SkuInventory resource

Property
Type
Description

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)

The SkuInventoryBatches resource

Property
Type
Description

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

The SkuInventoryPerWarehouse resource

Property
Type
Description

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

The InventoryPerWarehouse resource

Property
Type
Description

quantity

Integer (read-only)

Available for sale

warehouse_id

Integer (read-only)

Hive's unique warehouse ID

List all SKUs

GET https://app.hive.app/merchant_api/v1/skus

Returns SKUs ordered by descending creation time.

Query Parameters

Name
Type
Description

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.

{
  "data": [
    {
      "id": 9,
      "merchant_sku_id": "2218061549136",
      "name": "Morph II",
      "created_at": "2022-08-10T17:53:04.822+02:00",
      "cost_in_cents": null,
      "country_code_of_origin": null,
      "hs_code": null,
      "barcode": "2218061549136",
      "batch_tracking_enabled": true,
      "fulfilled_by": "hive",
      "weight_in_kg": 45.37,
      "image_url": "http://example.com/image.png",
      "status": "active",
      "inventory": {
        "stocked": 10000,
        "reserved": 0,
        "total": 10000
      },
      "inventory_per_warehouse": [
        {
          "warehouse_id": 22,
          "stocked": 6720,
          "reserved": 0,
          "total": 6720
        },
        {
          "warehouse_id": 65,
          "stocked": 3240,
          "reserved": 0,
          "total": 3240
        },
        {
          "warehouse_id": 38,
          "stocked": 40,
          "reserved": 0,
          "total": 40
        }
      ],
      "inventory_batches": [
        {
          "id": 827,
          "name": "Morph II - 827",
          "tracking_code": "A01234",
          "expiry_date": "2023-12-30",
          "stocked_quantities": [
            {
              "warehouse_id": 22,
              "quantity": 6720
            },
            {
              "warehouse_id": 65,
              "quantity": 3240
            }
          ]
        },
        {
          "id": 674,
          "name": "Morph II - 674",
          "tracking_code": "B56789",
          "expiry_date": null,
          "stocked_quantities": [
            {
              "warehouse_id": 38,
              "quantity": 40
            }
          ]
        }
      ]
    },
    {
      "id": 4,
      "merchant_sku_id": "4976808834423",
      "name": "Mr Moonstone",
      "created_at": "2022-08-10T17:53:04.507+02:00",
      "cost_in_cents": null,
      "country_code_of_origin": null,
      "hs_code": null,
      "barcode": "2218061549136",
      "batch_tracking_enabled": false,
      "fulfilled_by": "hive",
      "weight_in_kg": 24.92,
      "image_url": "http://example.com/image.png",
      "status": "active",
      "inventory": {
        "stocked": 10000,
        "reserved": 0,
        "total": 10000
      },
      "inventory_per_warehouse": [
        {
          "warehouse_id": 22,
          "stocked": 10000,
          "reserved": 0,
          "total": 10000
        },
        {
          "warehouse_id": 65,
          "stocked": 0,
          "reserved": 0,
          "total": 0
        }
      ],
      "inventory_batches": []
    }
  ],
  "pagination": {
    "current_page": 1,
    "item_count": 2,
    "page_count": 1,
    "items_per_page": 20
  }
}

Create a new SKU

POST https://app.hive.app/merchant_api/v1/skus

Request Body

Name
Type
Description

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)

{
  "id": 34,
  "merchant_sku_id": "HIVE_TSH_BLK_M",
  "name": "Hive T-Shirt (Black - M)",
  "barcode": "2218061549136",
  "batch_tracking_enabled": false,
  "fulfilled_by": "new",
  "created_at": "2022-08-10T17:53:04.438+02:00",
  "cost_in_cents": null,
  "country_code_of_origin": null,
  "hs_code": null,
  "weight_in_kg": 0.3,
  "image_url": "http://example.com/image.png",
  "status": "active",
  "inventory": {
    "stocked": 10000,
    "reserved": 0,
    "total": 10000
  },
  "inventory_per_warehouse": [
    {
      "warehouse_id": 22,
      "stocked": 10000,
      "reserved": 0,
      "total": 10000
    },
    {
      "warehouse_id": 65,
      "stocked": 0,
      "reserved": 0,
      "total": 0
    }
  ],
  "inventory_batches": []
}

Update an SKU

PATCH https://app.hive.app/merchant_api/v1/skus/{id}

Path Parameters

Name
Type
Description

id*

Integer

The (Hive) ID of the SKU to update

Request Body

Name
Type
Description

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

{
  "id": 4,
  "merchant_sku_id": "SKU_4",
  "name": "Mr Moonstone",
  "barcode": "2218061549136",
  "batch_tracking_enabled": true,
  "fulfilled_by": "hive",
  "created_at": "2022-08-10T17:53:04.507+02:00",
  "cost_in_cents": null,
  "country_code_of_origin": null,
  "hs_code": null,
  "weight_in_kg": 24.92,
  "image_url": "http://example.com/image.png",
  "status": "active",
  "inventory": {
    "stocked": 10000,
    "reserved": 0,
    "total": 10000
  },
  "inventory_per_warehouse": [
    {
      "warehouse_id": 22,
      "stocked": 10000,
      "reserved": 0,
      "total": 10000
    },
    {
      "warehouse_id": 65,
      "stocked": 0,
      "reserved": 0,
      "total": 0
    }
  ],
  "inventory_batches": [
    {
      "id": 579,
      "name": "Mr Moonstone - 579",
      "tracking_code": "A01234",
      "expiry_date": "2023-12-30",
      "stocked_quantities": [
        {
          "warehouse_id": 22,
          "quantity": 10000
        }
      ]
    }
  ]
}

Batch upsert SKUs

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.

Request Body

Name
Type
Description

skus*

Object[]

List of SKUs for upsert

{
    "data": [
        {
            "id": 12,
            "name": "Millenium Falcon",
            "country_code_of_origin": "DE",
            "hs_code": "567890",
            "created_at": "2023-04-25T22:12:16.123+02:00",
            "cost_in_cents": 110000,
            "weight_in_kg": 50.0,
            "merchant_sku_id": "2B",
            "image_url": "https://example.org/sw_merch/images/1.png",
            "status": "active",
            "barcode": "33444",
            "batch_tracking_enabled": false,
            "fulfilled_by": "new",
            "inventory": {
                "stocked": 0,
                "reserved": 0,
                "total": 0
            },
            "inventory_per_warehouse": [
              {
                "warehouse_id": 22,
                "stocked": 0,
                "reserved": 0,
                "total": 0
              }
            ],
            "inventory_batches": []
        },
        {
            "id": 11,
            "name": "Staff of Gandalf",
            "country_code_of_origin": "FR",
            "hs_code": "123456",
            "created_at": "2023-04-25T22:12:16.456+02:00",
            "cost_in_cents": 42000,
            "weight_in_kg": 2.0,
            "merchant_sku_id": "1A",
            "image_url": "https://example.org/lotr_merch/images/1.png",
            "status": "active",
            "barcode": "11222",
            "batch_tracking_enabled": true,
            "fulfilled_by": "hive",
            "inventory": {
                "stocked": 0,
                "reserved": 0,
                "total": 0
            },
            "inventory_batches": []
        }
    ]
}

Delete an SKU

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.

Path Parameters

Name
Type
Description

id*

Integer

The (Hive) ID of the SKU to delete

Last updated