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

# Products & Services Catalog

> Build the catalog of products, services, and plans that power invoices, estimates, and subscriptions

The Products catalog at `/dashboard/commerce/products/` is the source of truth for everything you sell — physical goods, services, retainers, and subscription plans. Every line item on an invoice, estimate, or recurring subscription pulls from this catalog (you can also add ad-hoc line items, but a clean catalog saves time and prevents pricing drift).

## What lives in the catalog

Three categories of items, all stored in `crm_products`:

* **One-time products and services** — Anything you bill once: a setup fee, a deliverable, a piece of hardware, a single consultation.
* **Recurring services** — Retainers, monthly maintenance, weekly deliverables. Sold via subscriptions and billed on a schedule.
* **Plans** — Tiered offerings (Starter / Pro / Enterprise) flagged with `is_plan: true`. Plans show in plan-pickers and roll up into MRR/ARR.

## Product fields

<Steps>
  <Step title="Name and description">
    The name appears on invoices and the client portal. The description is what the client reads — write it for them, not for internal sorting. Keep names short; put detail in the description.
  </Step>

  <Step title="SKU">
    Optional internal identifier. Useful for inventory tracking and accounting exports. Doesn't appear to clients unless you put it in a custom invoice template.
  </Step>

  <Step title="Price">
    Stored in cents to avoid floating-point rounding (`$49.00` becomes `4900`). Set the default currency at the account level; override per-product if you sell internationally.
  </Step>

  <Step title="Taxable flag">
    If checked, the configured tax rate applies when the product is added to an invoice. Tax-exempt clients (set on the contact) override this — see [tax handling in Settings](/commerce/payments#tax-configuration).
  </Step>

  <Step title="Recurrence">
    `one_time`, `monthly`, `quarterly`, `annual`, or `usage`. Drives whether the product can be attached to a subscription and how often it bills.
  </Step>

  <Step title="Plan flag">
    Set `is_plan: true` for tiered subscription plans. Plans get special treatment in plan-picker UIs and in MRR/ARR roll-ups.
  </Step>

  <Step title="Usage-based pricing">
    For metered products: the unit (per seat, per API call, per GB), unit price, and any included quantity. See [Subscriptions — usage-based](/commerce/subscriptions#usage-based-billing).
  </Step>
</Steps>

## Adding a product

<Tabs>
  <Tab title="One-time service">
    Use this for setup fees, single deliverables, or hardware.

    * Recurrence: **One-time**
    * Taxable: depends on your jurisdiction and the service type
    * Price: the per-unit price; quantity is set on the invoice line item

    Example: "Brand audit and report — \$2,500."
  </Tab>

  <Tab title="Monthly retainer">
    Use this for ongoing services billed every month.

    * Recurrence: **Monthly**
    * Plan flag: optional — set `is_plan: true` if you offer it as a tiered package
    * Price: the monthly rate

    Example: "SEO retainer — Standard — \$3,000/month."
  </Tab>

  <Tab title="Tiered plan">
    Use this for SaaS-style packaging — Starter, Pro, Enterprise.

    * Recurrence: **Monthly** or **Annual**
    * Plan flag: **`is_plan: true`**
    * Price: the plan's flat rate

    Add a separate product for each tier. The plan-picker on subscriptions groups them automatically.

    Example: "Starter Plan — $99/month", "Pro Plan — $299/month", "Enterprise Plan — \$999/month."
  </Tab>

  <Tab title="Usage-based product">
    Use this when the price scales with consumption.

    * Recurrence: **Usage**
    * Unit: e.g., per seat, per call, per GB
    * Unit price and any included quantity
    * Plan flag: optional, often paired with a base plan

    Example: "API requests — \$0.001 per call, first 10,000 included."
  </Tab>
</Tabs>

<Info>
  You can mix and match: a \$499/month base plan plus a usage-based add-on for overage charges. Both are products; they sit on the same subscription as separate line items.
</Info>

## Editing and archiving

Products are referenced by historical invoices, so deleting a product would orphan past line items. Instead, use the **archive** action — the product disappears from new invoice and subscription pickers, but historical records still resolve correctly.

If you need to change pricing on an existing product:

* New invoices and estimates pick up the new price immediately.
* Existing subscriptions stay on the price they were created with. To change a live subscription, edit the subscription's line item directly — see [Subscriptions — plan changes](/commerce/subscriptions#plan-changes).

<Warning>
  Editing a product's price doesn't propagate to active subscriptions. This is intentional — you don't want a typo to silently re-bill every client. Use subscription edits or migrations to roll out price changes.
</Warning>

## Using products on invoices and estimates

When you draft an invoice or estimate, the line-item picker searches `crm_products` by name and SKU. Adding a product copies the name, description, price, and tax flag onto the line item. From there you can:

* Adjust the **quantity** (defaults to 1)
* Override the **price** for this client (a per-line discount)
* Override the **description** (helpful for SOW-style invoices where the deliverable is custom)
* Add a **per-line discount** (percentage or fixed)

The product itself is unaffected by line-item edits. See [Invoices — line items](/commerce/invoices#line-items) and [Estimates — line items](/commerce/estimates#line-items).

## Importing a catalog

For a large catalog, import via CSV from the Products page. The columns map to product fields; missing optional fields use defaults. Row-by-row errors are reported so you can fix and retry.

The API at `/api/crm/products` supports `POST` for programmatic catalog management — useful when your products are derived from another system (a PIM, a project-management tool, or a code-generated SKU list).

## Best practices

* **One product per billable item.** Don't create one product for "Consulting" and price it differently every invoice — make it harder to read your reports. Create separate products like "Strategy Consulting", "Implementation Consulting", "Audit & Review."
* **Use plans (`is_plan: true`) only for true tiers.** A monthly retainer isn't a plan unless you offer multiple of them as packaged tiers.
* **Set descriptions for the client.** "Quarterly business review covering pipeline, retention, and goals" reads better on an invoice than "QBR."
* **Archive aggressively.** Stale products clog the line-item picker. Archive everything you don't actively sell.

## Common catalog structures

How successful service businesses organize their catalog:

<Tabs>
  <Tab title="Agency">
    * Tiered retainers as plans: "Standard / Premium / Enterprise" with `is_plan: true`
    * One-off services: "Audit", "Workshop", "Strategy Session"
    * Add-ons: "Extra hours", "Rush delivery", "Premium reporting"
  </Tab>

  <Tab title="Consulting firm">
    * Engagement types as one-time products: "Discovery", "Implementation", "Optimization"
    * Recurring advisory: "Monthly Advisory" as recurring monthly
    * T\&M billing: "Senior Consultant Hourly", priced per hour, quantity billed per invoice
  </Tab>

  <Tab title="B2B SaaS">
    * Plans with `is_plan: true`: "Starter / Pro / Enterprise"
    * Usage add-ons: "Per-seat overage", "API request overage" with usage recurrence
    * Professional services: "Onboarding", "Custom integration" as one-time
  </Tab>
</Tabs>

## What's next?

<CardGroup cols={2}>
  <Card title="Send Your First Invoice" icon="rocket" href="/how-tos/send-first-invoice">
    Use a product on a real invoice end-to-end.
  </Card>

  <Card title="Set Up Subscriptions" icon="repeat" href="/how-tos/setup-recurring-subscription">
    Attach a recurring product to a client.
  </Card>

  <Card title="Invoices Reference" icon="file-invoice-dollar" href="/commerce/invoices">
    Full invoice lifecycle and field reference.
  </Card>

  <Card title="Subscriptions Reference" icon="repeat" href="/commerce/subscriptions">
    Plan changes, proration, and recurring billing.
  </Card>
</CardGroup>