# 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](https://en.wikipedia.org/wiki/ISO_3166-1) code of country of origin                               |
| created\_at                                         | ISO8601 datetime (read-only)                                                                   | When this SKU was created                                                                                               |
| dangerous\_good                                     | Boolean (ready-only)                                                                           | Sku is a dangerous good                                                                                                 |
| fulfilled\_by                                       | String (read-only)                                                                             | <p>Who is fulfilling this SKU. Valid values:<br><strong>hive</strong>, <strong>other</strong>, <strong>new</strong></p> |
| h\_codes                                            | Array of String (read-only)                                                                    | Hazardous good H Codes                                                                                                  |
| hazardous\_good                                     | Boolean (ready-only)                                                                           | Sku is a hazardous good                                                                                                 |
| hs\_code                                            | String                                                                                         | The general [Harmonized System](https://en.wikipedia.org/wiki/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](#the-skuinventory-resource) object (read-only)                                | Current inventory                                                                                                       |
| inventory\_batches                                  | Array of [SkuInventoryBatches](#the-skuinventorybatches-resource) object (read-only)           | Current inventory per batch                                                                                             |
| inventory\_per\_warehouse                           | Array of [SkuInventoryPerWarehouse](#the-skuinventoryperwarehouse-resource) object (read-only) | Current inventory per warehouse                                                                                         |
| merchant\_sku\_id<mark style="color:red;">\*</mark> | String                                                                                         | SKU code as provided by the merchant                                                                                    |
| name<mark style="color:red;">\*</mark>              | String                                                                                         | Name of this SKU                                                                                                        |
| un\_names                                           | Array of String (ready-only)                                                                   | Dangerous good UN Numbers                                                                                               |
| status                                              | String (read-only)                                                                             | <p>Valid values:<br><strong>active</strong>, <strong>deleted</strong></p>                                               |
| weight\_in\_kg                                      | Float                                                                                          | Weight of SKU in kilograms                                                                                              |

{% hint style="info" %} <mark style="color:red;">\*</mark>Required properties when creating a new record.
{% endhint %}

## 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](#the-inventoryperwarehouse-resource) 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

<mark style="color:blue;">`GET`</mark> `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. |

{% tabs %}
{% tab title="200: OK " %}

```json
{
  "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",
      "dangerous_good": true,
      "un_numbers": ["UN3481"],
      "hazardous_good": false,
      "h_codes": [],
      "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",
      "dangerous_good": true,
      "un_numbers": ["UN3481"],
      "hazardous_good": false,
      "h_codes": [],
      "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
  }
}
```

{% endtab %}
{% endtabs %}

## Create a new SKU

<mark style="color:green;">`POST`</mark> `https://app.hive.app/merchant_api/v1/skus`

#### Request Body

| Name                                                | Type    | Description                                                                               |
| --------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------- |
| name<mark style="color:red;">\*</mark>              | String  | A human-readable name or title                                                            |
| merchant\_sku\_id<mark style="color:red;">\*</mark> | 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](https://en.wikipedia.org/wiki/ISO_3166-1) code of country of origin |
| hs\_code                                            | String  | [Harmonized System](https://en.wikipedia.org/wiki/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)                       |

{% tabs %}
{% tab title="201: Created The SKU was created successfully" %}

```json
{
  "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",
  "dangerous_good": true,
  "un_numbers": ["UN3481"],
  "hazardous_good": false,
  "h_codes": [],
  "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": []
}
```

{% endtab %}

{% tab title="400: Bad Request The request was malformed" %}

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

{% endtab %}

{% tab title="422: Unprocessable Entity The data was invalid" %}

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

{% endtab %}
{% endtabs %}

## Update an SKU

<mark style="color:purple;">`PATCH`</mark> `https://app.hive.app/merchant_api/v1/skus/{id}`

#### Path Parameters

| Name                                 | Type    | Description                        |
| ------------------------------------ | ------- | ---------------------------------- |
| id<mark style="color:red;">\*</mark> | 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](https://en.wikipedia.org/wiki/ISO_3166-1) code of country of origin |
| hs\_code                  | String  | [Harmonized System](https://en.wikipedia.org/wiki/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                                                      |

{% tabs %}
{% tab title="200: OK The SKU was updated successfully" %}

```json
{
  "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",
  "dangerous_good": true,
  "un_numbers": ["UN3481"],
  "hazardous_good": false,
  "h_codes": [],
  "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
        }
      ]
    }
  ]
}
```

{% endtab %}

{% tab title="404: Not Found There was no SKU matching the given ID" %}

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

{% endtab %}

{% tab title="422: Unprocessable Entity The data was invalid" %}

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

{% endtab %}

{% tab title="400: Bad Request The request was malformed" %}

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

{% endtab %}
{% endtabs %}

## Batch upsert SKUs

<mark style="color:green;">`POST`</mark> `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<mark style="color:red;">\*</mark> | Object\[] | List of SKUs for upsert |

{% tabs %}
{% tab title="200: OK All SKUs were upserted successfully" %}

```json
{
    "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",
            "dangerous_good": true,
            "un_numbers": ["UN3481"],
            "hazardous_good": false,
            "h_codes": [],
            "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",
            "dangerous_good": true,
            "un_numbers": ["UN3481"],
            "hazardous_good": false,
            "h_codes": [],
            "inventory": {
                "stocked": 0,
                "reserved": 0,
                "total": 0
            },
            "inventory_batches": []
        }
    ]
}
```

{% endtab %}

{% tab title="400: Bad Request Incorrect request body format" %}

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

{% endtab %}

{% tab title="400: Bad Request Too many items are passed" %}

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

{% endtab %}

{% tab title="422: Unprocessable Entity Some of passed SKUs is invalid" %}

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

{% endtab %}
{% endtabs %}

## Delete an SKU

<mark style="color:red;">`DELETE`</mark> `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<mark style="color:red;">\*</mark> | Integer | The (Hive) ID of the SKU to delete |

{% tabs %}
{% tab title="204: No Content The SKU was deleted successfully" %}

{% endtab %}

{% tab title="404: Not Found There was no SKU matching the given ID or it is already deleted" %}

{% endtab %}
{% endtabs %}