SKUs

What is a SKU?

A SKU (Stock Keeping Unit) represents a specific purchasable variant of a product within a merchant's Offer. 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:

{
  "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 or applied to an 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}