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

# Catalog

> Use products and prices to keep checkout and payment links consistent.

Catalog objects turn one-off amounts into reusable commercial building blocks. Products describe what you sell. Prices describe how much a buyer pays.

## The model

Products describe what you sell; prices describe how much a buyer pays for
it; checkout sessions and payment links turn prices into line items.

* **Product** — what you sell ("Starter plan", "Donation").
  Carries name, description, images, unit label, kind, metadata, cross-sells.
* **Price** — belongs to one product; carries `unit_amount`, `currency`,
  `nickname`, active state. A product can hold many prices (monthly vs
  annual, USD vs EUR) with one default.
* **Line item** — a price selected for a specific checkout or link
  (`{"price_id": "price_...", "quantity": 2}`). Checkout sessions also
  accept inline line items for one-off amounts; payment links are always
  catalog-backed.
* **Optional item** — a buyer-selectable add-on line: expedited service,
  setup packages, cross-sells.

On Node, `npm install @ionicfi/sdk` gives you typed calls for every request
below; the [server SDK](/sdks/server) guide has details. Each example also
shows raw curl.

## Create a product

<CodeGroup>
  ```ts TypeScript theme={null}
  import { Ionic } from "@ionicfi/sdk";

  const ionic = new Ionic({ token: process.env.IONIC_SECRET_KEY });

  const product = await ionic.catalog.products.create({
    name: "Starter plan",
    description: "Monthly access for small teams",
    images: ["https://example.com/starter.png"],
    unit_label: "seat",
    product_kind: "service",
    metadata: { tier: "starter" },
  });
  ```

  ```bash curl theme={null}
  curl https://api.ionicfi.com/v1/products \
    -H "Authorization: Bearer sk_v1_test_..." \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Starter plan",
      "description": "Monthly access for small teams",
      "images": ["https://example.com/starter.png"],
      "unit_label": "seat",
      "product_kind": "service",
      "metadata": {
        "tier": "starter"
      }
    }'
  ```
</CodeGroup>

The product response includes the default price, representative price, price count, product kind, cross-sells, and timestamps.

## Create a price

<CodeGroup>
  ```ts TypeScript theme={null}
  const price = await ionic.catalog.prices.create({
    product_id: product.id,
    unit_amount: 2900,
    currency: "usd",
    nickname: "Monthly",
    make_default: true,
    metadata: { billing_period: "monthly" },
  });
  ```

  ```bash curl theme={null}
  curl https://api.ionicfi.com/v1/prices \
    -H "Authorization: Bearer sk_v1_test_..." \
    -H "Content-Type: application/json" \
    -d '{
      "product_id": "prod_123",
      "unit_amount": 2900,
      "currency": "usd",
      "nickname": "Monthly",
      "make_default": true,
      "metadata": {
        "billing_period": "monthly"
      }
    }'
  ```
</CodeGroup>

## Use prices in checkout

```json theme={null}
{
  "mode": "payment",
  "line_items": [
    {
      "price_id": "price_123",
      "quantity": 3
    }
  ],
  "success_url": "https://example.com/success",
  "cancel_url": "https://example.com/cancel"
}
```

## Product fields

| Field          | Purpose                                               |
| -------------- | ----------------------------------------------------- |
| `name`         | Buyer-facing product name.                            |
| `description`  | Longer product description.                           |
| `images`       | Product image URLs.                                   |
| `metadata`     | Your key-value data.                                  |
| `unit_label`   | Label such as `seat`, `license`, or `package`.        |
| `product_kind` | Application-defined kind for UI and reporting.        |
| `cross_sells`  | Related products or offers used by checkout builders. |

## Price fields

| Field          | Purpose                            |
| -------------- | ---------------------------------- |
| `product_id`   | Product this price belongs to.     |
| `unit_amount`  | Minor currency units.              |
| `currency`     | Currency code, usually `usd`.      |
| `nickname`     | Your label for the price.          |
| `make_default` | Make this product's default price. |
| `metadata`     | Your key-value data.               |

## When to use inline amounts instead

Inline amounts are useful for prototypes, quotes, and one-off service invoices. Catalog objects are better once a price is reused, reported on, exposed in a dashboard, or selected by a payment link builder.