Catalog: offerings and variants

The catalog is governed: it lives in Quikstik, every price in a charge is resolved from it on the server, and clients only ever read it. That is what lets the API promise that no request carries an amount.

Offerings and variants

An offering is a product as the customer sees it — a guided tour, a half-day rental, a private charter. An offering has one or more variants, and a variant is what is actually scheduled, priced and sold. Variants carry:

• capacity — per-departure participant capacity (the leaf of the capacity chain; see Availability),
• duration_minutes,
• meeting_point — a structured name and address,
• units — the unit-of-sale label (per rider, per day),
• participant_rules_text — free-text eligibility rules (age, height, licence) carried verbatim,
• add_ons — optional extras with their own prices (a child trailer, a cooler).

GET /offerings lists offerings; GET /offerings/{offering_id} returns the offering with its variant summaries; GET /offerings/{offering_id}/variants/{variant_id} returns the full variant.

Offerings are modelled broadly: fixed-departure experiences (a tour leaving at 9:15), duration-based rentals (a bike for the day, a van for a week), and plain SKU commerce all fit the same shape. A kind discriminator is reserved for telling them apart.

Pricing schedules

Each variant has a price book: a set of rate rules, each with a currency, an inclusive effective date range, an optional demand class, and the rate. Rules within a lane may not overlap. Operators set it with PUT /offerings/{offering_id}/variants/{variant_id}/pricing-schedule, which also sets the variant’s availability recurrence (which days, which start times, in which time zone). A malformed schedule is rejected before anything is written.

A multi-day rental is priced as units × rental_days at the per-day rate; capacity is committed at units regardless of days.

Demand classes

A demand class is a pricing and allocation lane: the direct storefront (default), an OTA, a corporate or membership rate. Prices resolve within the lane the sale is made in, and capacity can be withheld per lane so that, say, an OTA cannot sell the last seats that are being held for direct guests. Pass demand_class on a purchase; the storefront uses default.

Tax

Tax is tenant configuration (POST /merchants/tax-config), applied server-side when a charge is priced. Responses report net_minor, tax_minor and gross_minor separately so the breakdown can be shown and reconciled.

Provisioning

Operators create or replace offerings and their variants with POST /offerings (idempotent by identity) and set each variant’s capacity policy with POST /offerings/capacity-policy. These are Admin writes; a publishable key cannot reach them.