Variants and options

A variant is the unit a shopper buys: a SKU with its own price. Every checkout line references a variant_id, never a product directly. This guide covers how Flightdeck models variants and how to create, price, and update them.

Prerequisites

A merchant key holding manage:own_catalog.
A product to attach variants to — see Add products.

How the variant model works

⚠️

Flightdeck does not model separate “options” and “option values” (a size axis crossed with a color axis that auto-generates a variant matrix). A product owns a flat list of variants, and each variant is a self-contained SKU. You express choices by giving each variant a descriptive label — e.g. “5mg vial”, “10mg vial” — and creating one variant per purchasable configuration yourself.

A variant carries exactly these fields:

Field	Type	Notes
`sku`	string	Required, immutable once set. Your stock-keeping identity.
`label`	string or null	Human-readable variant name (e.g. “5mg vial”).
`price_cents`	integer	Required, non-negative. Integer cents (`4999` = $49.99).
`currency`	string	Defaults to `usd`.
`weight_grams`	integer or null	Positive integer, used for shipping.

The public catalog serves each product with its variants array inline, so a storefront reads a product once and has every purchasable option in hand.

Add and price variants

Create one variant per configuration

Add each purchasable configuration as its own variant. To offer 5mg and 10mg vials at different prices, create two variants under the same product.

curl -X POST https://api.ruo.pro/v1/merchant/catalog/products/{productId}/variants \
  -H "Authorization: Bearer fdk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "sku": "NOVA-BPC-5MG", "label": "5mg vial", "price_cents": 4999 }'
 
curl -X POST https://api.ruo.pro/v1/merchant/catalog/products/{productId}/variants \
  -H "Authorization: Bearer fdk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "sku": "NOVA-BPC-10MG", "label": "10mg vial", "price_cents": 8999 }'

Each returns a 201 with { "variant": { ... } }. sku and a non-negative integer price_cents are required; omitting or malforming either is a 400.

Update a variant’s price or label

Change price, label, or weight with a PATCH. The SKU is not updatable — it stays the stable identity. Only the fields you include change.

curl -X PATCH https://api.ruo.pro/v1/merchant/catalog/products/{productId}/variants/{variantId} \
  -H "Authorization: Bearer fdk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "price_cents": 5499, "label": "5mg vial (new batch)" }'

Field	Rule
`label`	String or `null`.
`price_cents`	Non-negative integer.
`weight_grams`	Positive integer or `null`.

A 200 returns the updated variant.

List a product’s variants

Read every variant on a product with the merchant credential:

curl https://api.ruo.pro/v1/merchant/catalog/{productId}/variants \
  -H "Authorization: Bearer fdk_your_key_here"

The self-serve variant write routes are live HTTP endpoints not yet in the published OpenAPI document, so the typed SDK does not cover them — use curl or a raw fetch for creates and updates.

Per-variant pricing for customer groups

Base price_cents is the list price every shopper sees. To offer B2B, wholesale, or VIP pricing, put customers into a pricing group and set per-variant overrides on that group (also gated by manage:own_catalog, since pricing is catalog). At checkout the server resolves the right price from the customer’s group — the client never sends a price. Pricing groups live under /v1/merchant/pricing-groups.

Add products — creating the product a variant hangs off.
API reference — the full variant and pricing-group field shapes.
Integrate checkout — how variant_id drives an order.

Add products Collections