# SKUs

### What is a SKU?

A **SKU (Stock Keeping Unit)** represents a specific purchasable variant of a product within a merchant's [Offer](https://docs.violet.io/api-reference/catalog/offers). SKUs are the atomic unit of inventory and pricing in Violet's catalog - when a customer adds an item to their cart, they're adding a specific SKU.

### Data Model Hierarchy

```
Offer (merchant's listing of that product)
   └── SKU (specific purchasable variant)
```

* **Offer**: A merchant's specific listing with their pricing and availability.
* **SKU**: A purchasable variant with unique attributes (e.g., "Classic T-Shirt - Blue - Large").

A single Offer can have multiple SKUs representing different variants (sizes, colors, configurations).

### Key SKU Properties

| Property            | Type    | Description                                                |
| ------------------- | ------- | ---------------------------------------------------------- |
| `id`                | integer | Violet's unique SKU identifier                             |
| `external_id`       | string  | The merchant's own SKU identifier                          |
| `merchant_id`       | integer | The merchant selling this SKU                              |
| `offer_id`          | integer | The parent Offer this SKU belongs to                       |
| `name`              | string  | Display name (often includes variant details)              |
| `sale_price`        | integer | Current selling price in minor units (cents)               |
| `retail_price`      | integer | MSRP in minor units                                        |
| `currency`          | string  | ISO 4217 currency code (default: source merchant currency) |
| `in_stock`          | boolean | Whether the SKU is currently in stock                      |
| `qty_available`     | integer | Available inventory quantity                               |
| `inventory_tracked` | boolean | Whether inventory is actively managed                      |
| `status`            | enum    | `AVAILABLE`, `UNAVAILABLE`, `ARCHIVED`, `FOR_DELETION`     |
| `type`              | enum    | `PHYSICAL`, `DIGITAL`, `VIRTUAL`                           |

### Product Identifiers

SKUs can include standard product identifiers for matching and verification:

* `upc` - Universal Product Code
* `ean` - European Article Number
* `gtin` - Global Trade Item Number
* `asin` - Amazon Standard Identification Number
* `isbn` - ISBN (for books)

### Variant Values

SKUs include a `variant_values` array containing key-value pairs that describe what makes this variant unique:

```json
{
  "variant_values": [
    { "name": "Size", "value": "Large" },
    { "name": "Color", "value": "Blue" }
  ]
}
```

### SKU Dimensions

Physical SKUs can include dimensional data for shipping calculations:

* `weight` - Product weight
* `height`, `width`, `length` - Physical dimensions
* Separate `shipping_dimensions` may be provided for packaged dimensions

### Common Use Cases

#### Retrieving SKU Details

Use `GET /catalog/skus/{sku_id}` to fetch complete SKU information including pricing, availability, and variant details.

### Pricing Notes

* Prices are stored in **minor units** (cents for USD). A `sale_price` of `2500` represents $25.00.
* `sale_price` is the current selling price; `retail_price` is the suggested retail price.
* Currency conversion is available - pass your desired currency to receive converted prices.

### Availability & Inventory

* Check `in_stock` for a quick availability boolean.
* `qty_available` provides the actual quantity when `inventory_tracked` is `true`.
* `status` must be `AVAILABLE` for the SKU to be purchasable.
* SKUs with `ARCHIVED` or `FOR_DELETION` status are no longer active in the catalog.

### Relationship to Orders

When items are [added to a cart](https://docs.violet.io/api-reference/orders-and-checkout/cart-items/add-sku-to-cart) or [applied to an order](https://docs.violet.io/api-reference/orders-and-checkout/orders/create-order), they reference the specific SKU ID. Changes to SKU availability (out of stock, archived) are automatically communicated to active carts containing that SKU.

***

**Available endpoints:**

```
GET /v1/catalog/skus/{sku_id}
```