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	2-letter ISO 3166-1 code of country of origin
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	The general Harmonized System (HS) code for the SKU
id	Integer (read-only)	Hive unique identifier for this SKU
image_url	String	Publicly accessible URL of an image for this SKU
inventory	A SkuInventory object (read-only)	Current inventory
inventory_batches	Array of SkuInventoryBatches object (read-only)	Current inventory per batch
inventory_per_warehouse	Array of SkuInventoryPerWarehouse object (read-only)	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	A InventoryPerWarehouse object (read-only)	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.

200: OK

{
  "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	2-letter ISO 3166-1 code of country of origin
hs_code	String	Harmonized System code
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)

201: Created The SKU was created successfully

{
  "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": []
}

400: Bad Request The request was malformed

{
  "success": false,
  "errors": [
    "bad request"
  ]
}

422: Unprocessable Entity The data was invalid

{
  "success": false,
  "errors": [
    "Name can't be blank",
    "Merchant sku can't be blank"
  ]
}

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	2-letter ISO 3166-1 code of country of origin
hs_code	String	Harmonized System code
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

200: OK The SKU was updated successfully

{
  "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
        }
      ]
    }
  ]
}

404: Not Found There was no SKU matching the given ID

{
  "success": false,
  "errors": [
    "record not found"
  ]
}

422: Unprocessable Entity The data was invalid

{
  "success": false,
  "errors": [
    "Name can't be blank"
  ]
}

400: Bad Request The request was malformed

{
  "success": false,
  "errors": [
    "bad request"
  ]
}

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

200: OK All SKUs were upserted successfully

{
    "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": []
        }
    ]
}

400: Bad Request Incorrect request body format

{
  "success": false,
  "errors": [
    "Pass array with at least one item for upsert by 'skus' key"
  ]
}

400: Bad Request Too many items are passed

{
  "success": false,
  "errors": [
    "Disallowed to pass more than 100 items at once"
  ]
}

422: Unprocessable Entity Some of passed SKUs is invalid

{
  "success": false,
  "errors": [
    "Name can't be blank"
  ]
}

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

204: No Content The SKU was deleted successfully

404: Not Found There was no SKU matching the given ID or it is already deleted