Catalog

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 guide has details. Each example also shows raw curl.

Create a product

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" },
});

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"
    }
  }'

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

Create a price

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" },
});

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"
    }
  }'

Use prices in checkout

{
  "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.

Catalogs for connected merchants

A platform creates and updates a connected merchant’s products and prices with its platform secret key. Pass the merchant ID as the server SDK’s account option (@ionicfi/sdk 0.4.4 or later) or send it in the Ionic-Account header. The platform key and the merchant’s connection both need products:write. See Connect billing to put a customer on the plan.

const product = await ionic.catalog.products.create(
  { name: "Pro plan", "Idempotency-Key": "merchant:mer_BBBBBBBBBBBBBB:product:pro" },
  { account: "mer_BBBBBBBBBBBBBB" },
);

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.

What’s next

Sell with checkout

Turn catalog prices into line items on a hosted checkout page.

Share a payment link

Create a reusable link backed by a catalog price.

Bill recurring prices

Attach recurring prices to a customer and bill each period.

Payments

Manage payments

The model

Create a product

Create a price

Use prices in checkout

Product fields

Price fields

Catalogs for connected merchants

When to use inline amounts instead

What’s next

Sell with checkout

Share a payment link

Bill recurring prices

​The model

​Create a product

​Create a price

​Use prices in checkout

​Product fields

​Price fields

​Catalogs for connected merchants

​When to use inline amounts instead

​What’s next

Sell with checkout

Share a payment link

Bill recurring prices

The model

Create a product

Create a price

Use prices in checkout

Product fields

Price fields

Catalogs for connected merchants

When to use inline amounts instead

What’s next