SKUs

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