> ## Documentation Index
> Fetch the complete documentation index at: https://docs.colossal.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Products

> The catalog entity and its Product, Variant and Price hierarchy.

A product is the top-level catalog entity (for example "Pro Plan" or "Logo T-Shirt"). Every product belongs to a project and follows a three-level structure: **Product → Variant → Price**. Media and deliverables attach at the variant level.

<Frame>
  <iframe src="https://pub-ba469dfa04d142b989e362d6623888e7.r2.dev/product-hierarchy-2.html" style={{width: "100%", height: "580px", border: "none"}} />
</Frame>

## How to use

Products are a standalone primitive. You can use them as part of the Colossal platform — or use them to enhance an existing platform by syncing products to and from your third-party systems.
Products can be used with [cart](/concepts/cart) and [checkout](/concepts/checkout-and-payments).

## Surfaces

<CardGroup cols={2}>
  <Card title="Events" icon="bolt" href="/apps/colossal-app/events#products">
    Events for products, variants, prices, and deliverables.
  </Card>

  <Card title="Actions" icon="play" href="/apps/colossal-app/actions#products">
    12 actions covering products, variants, prices, and deliverables.
  </Card>

  <Card title="Tools" icon="sparkles" href="/apps/colossal-app/tools#products">
    LLM-callable read and write tools for product management.
  </Card>

  <Card title="Storefront API" icon="code" href="/api-reference/products">
    GraphQL queries for fetching products on your storefront.
  </Card>
</CardGroup>

## Variants

A variant represents a purchasable option within a product (for example, size "Large" or tier "Annual"). Each variant has its own prices, media, and deliverables.

Today, every product has a single default variant (visible as `default_variant` in the sample payload below). Multiple variants per product is *coming soon*.

## Pricing

A variant can have multiple prices for different billing models. For example, a one-time purchase, a monthly subscription, or an annual plan with a deeper discount. Prices have a currency, a billing model, an optional trial duration, and optional recurring intervals (`month` or `year`) for subscriptions. Recurring billing is coming soon.

Two pricing models are supported.

* **Linear.** Flat unit price. Currently the only available model.
* **Volume.** Tiered pricing based on quantity. *(coming soon)*

## Draft and published content

Products, variants, and prices each have a dual-content model with `published_content` and `draft_content` fields.

* **Draft content** holds in-progress edits that are not yet visible on the storefront.
* **Published content** is what the storefront API returns.
* When you publish, draft content becomes published content and the draft is cleared.

## Product states

<AccordionGroup>
  <Accordion title="Draft" icon="pen-line">
    Has `draft_content` but no `published_content`. Not visible on the storefront.
  </Accordion>

  <Accordion title="Published" icon="circle-check">
    Has `published_content`. Visible to customers via the storefront API.
  </Accordion>

  <Accordion title="Archived" icon="box-archive">
    `is_archived` is `true`. Hidden from the storefront and catalog listings.
  </Accordion>
</AccordionGroup>