> ## Documentation Index > Fetch the complete documentation index at: https://docs.fluid.app/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > For new direct REST integrations, use the v2026-04 surfaces. The @fluid-app FairShare SDK continues to use its own published public-v2025-06 contract. > Authenticate with the header Authorization: Bearer ; public storefront read endpoints require no auth. > Lists use cursor pagination via the page[cursor] and page[limit] query params; follow meta.pagination.next_cursor until it is null. > Never use /api/company/v1 or /api/v1 paths, page/per_page params, or offset pagination — they are legacy. > The OpenAPI specs under api-reference/ are the authoritative contracts; prefer them over prose when in doubt. api-reference/storefront-v2026-04.yaml covers the v2026-04 storefront surface (/api/v202604/... paths); api-reference/auth-v0.yaml covers the unversioned auth surface (/api/... paths — authentication, MFA, social auth, and token exchange); api-reference/checkout-v2026-04.yaml covers the v2026-04 checkout surface (/api/checkout/v2026-04/... paths — carts, cart auth, discounts, items, subscriptions, orders, enrollments, and store config); api-reference/public-v2025-06.yaml covers the Public SDK surface used by the @fluid-app FairShare SDK, including its parallel cart lifecycle, browser integrations, versioned payment callbacks, unversioned public utilities, and the cart price-override operation; api-reference/payment-v2026-04.yaml covers the v2026-04 payment gateway admin surface (/api/payment/v2026-04/... paths, bearer-authenticated — gateway CRUD, gateway purchase/authorize/$0-verify, transaction list/show and capture/void/credit, and merchant payment configuration); api-reference/payments-v2026-04.yaml covers the v2026-04 cart payment surface (/api/payments/v2026-04/carts/{cart_token}/... paths, authenticated by the cart token in the path with no bearer — payment-method selection, VGS card tokenization, 3D Secure verification, and PayPal/Braintree/Klarna/Apple Pay flows); api-reference/commerce-v2026-04.yaml covers the v2026-04 commerce order-editing surface (/api/v202604/orders/{order_id}/edits paths, bearer-authenticated — post-checkout order edits that atomically insert items and add adjustments/discounts, with an optional dry-run preview); api-reference/webhooks-v0.yaml covers the unversioned webhooks surface (/api/... paths — webhook registration, delivery payloads, callback registrations, company events, and webhook/callback schemas). > Successful responses wrap the resource payload alongside a top-level integer status and a meta object. # Company Product show > Token-authenticated; resolves by id (the canonical company identifier). Returns any Product regardless of lifecycle. Pricing is COUNTRY-RELATIVE — the `country` parameter selects the per-country variant price/currency. ## OpenAPI ````yaml /api-reference/storefront-v2026-04.yaml get /api/v202604/company/products/{id} openapi: 3.1.0 info: title: Fluid Storefront v2026-04 API version: v2026-04 description: | The modernized storefront surface, covering all eight storefront resources: **Categories**, **Collections**, **Products**, **Posts**, **Pages**, **Media**, **Enrollment Packs**, and **Playlists**. ## Two surfaces Every resource is exposed twice, and the pair is the thing to understand first: - **Public** — `/api/v202604/{resource}` and `/api/v202604/{resource}/{slug}`. Unauthenticated (`security: []`); the store is resolved from the request subdomain. Addressed by `slug`, the same identifier that appears in `canonical_url`. Returns only live rows — non-live content never leaks here. - **Company** — `/api/v202604/company/{resource}`. Bearer-token authenticated, addressed by `id`, and returns every row whatever its lifecycle state, so an admin can manage drafts and archives. Full CRUD plus the standardized `shares`, `lighthouse`, and `compliance` member actions on each resource. Path segments use the storefront's nouns, not the database's: `enrollment-packs` and `playlists` (the Library model). ## One response shape Every resource response opens with the same canonical "common top", in the same order, before any resource-specific fields: id, slug, title, description, image_url, canonical_url, images, active, status, publish_at, seo, metafields, languages That means a consumer can render any storefront resource from one code path. `seo` is always present and always fully populated — the server resolves it through a priority chain (SEO record → resource field → store default → built-in), so there is no client-side fallback logic and the API can never disagree with the rendered ``. `metafields`, `languages`, and (where applicable) `countries` are always arrays, never null. ## Lifecycle `status` is the canonical four-value contract — `draft`, `scheduled`, `published`, `archived` — and resolves at the API boundary: a stored `scheduled` row whose `publish_at` has passed reads as `published` with no write required. `active` is the separate merchant on/off toggle; a resource is live only when it is both active and resolved-published. Company create and update auto-queue Lighthouse and compliance scans, so the scores on the member actions always describe the current state of the resource. ## Listing and pagination Index endpoints share one query surface: `lang`, `q` (Elasticsearch over title and description), `filter[…]`, `sort`, and cursor pagination via `page[cursor]` / `page[limit]` (default 25, max 100). Follow `meta.pagination.next_cursor`; do not construct cursors. Products additionally take `country`, which selects the country-relative price and currency AND gates availability. Categories and Collections expose their products from their own path — `GET /api/v202604/categories/{slug}/products` — which is the products catalog scoped to one owner, with the same card shape, filters, sorting, and pagination. ## Translating a resource Translations are written inline on the resource's own create/update. There is no separate translations endpoint and no `translations` object in the payload — the `lang` query parameter selects the locale a request reads or writes. **Read** a locale with `lang` on any GET: GET /api/v202604/company/collections/4821?lang=fr Translated fields (`title`, `description`, `image_url`, and each resource's own translated fields) come back inline in that locale. On the public surface any field with no `fr` translation falls back to its `en` value, so a partially-translated resource never renders blank. The `languages` array on every response lists exactly the locales that carry a translation, always including the default. **Write** a locale with `lang` on POST/PATCH: PATCH /api/v202604/company/collections/4821?lang=fr { "collection": { "title": "Essentiels bien-être" } } Omitting `lang` writes the store's default locale — the store's own default language, not the platform's. A store selling in French treats `lang=fr` as its default write. A translation PATCH is TEXT ONLY: against any other locale, everything but the translated fields is ignored, so translating a title can never regenerate the slug, move `status`, or change `country_isos`, metafields, SEO, or associations. Send those in a request against the store's default locale instead. Creating is different: POST always writes the store's default locale whatever `lang` says, and keeps its full payload. A resource created under a translation would have no value in the store's own language and would take its slug from the translation. `lang` is still validated on POST, so an unsupported locale is a 422 rather than a surprise. A `lang` the store does not sell in returns 422 — translations are never written to a locale the store has not enabled. Add the language to the store first. The typical flow is: create in the default locale, then one PATCH per additional locale carrying only the translated text. contact: email: support@fluid.app license: name: Proprietary identifier: LicenseRef-Proprietary servers: - url: https://api.fluid.app - url: https://{company}.fluid.app description: Production server with company subdomain variables: company: default: myco description: Company subdomain security: [] tags: - name: storefront description: | Unauthenticated public surface that backs storefront pages and AEO crawlers. All operations are `security: []`. - name: company description: | Token-authenticated company surface that backs the admin UI and integrations. paths: /api/v202604/company/products/{id}: get: tags: - company summary: Company Product show description: | Token-authenticated; resolves by id (the canonical company identifier). Returns any Product regardless of lifecycle. Pricing is COUNTRY-RELATIVE — the `country` parameter selects the per-country variant price/currency. operationId: companyProductsShow parameters: - name: id description: The unique identifier of the product. in: path required: true schema: type: integer - $ref: '#/components/parameters/Lang' - $ref: '#/components/parameters/Country' responses: '200': description: The Product. content: application/json: schema: $ref: '#/components/schemas/ProductCompanyShowResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' security: - bearer_auth: [] components: parameters: Lang: name: lang in: query required: false description: | Response locale. ISO code (e.g. `fr`, `de`). When omitted, responds in the company's default locale. On the public surface, falls back to `en` for any translated field missing in the requested locale. schema: type: string example: fr Country: name: country in: query required: false description: | ISO-2 country code that selects COUNTRY-RELATIVE Product pricing. Product-only — Categories and other storefront resources use `filter[country]` as an access-list visibility filter instead. For Products, `country` drives the `pricing` block and each variant's `variant_countries`: it picks which per-country variant price and currency are rendered. On the catalog it also drops products with no active variant in the requested country. When omitted, falls back to the company's default country. schema: type: string example: GB schemas: ProductCompanyShowResponse: allOf: - $ref: '#/components/schemas/Envelope' - type: object required: - product properties: product: $ref: '#/components/schemas/ProductAuthenticated' Envelope: type: object description: | Shared success envelope for list / show / create / update responses: the resource payload is returned alongside a top-level integer `status` and `meta`. Composed onto each resource response via `allOf`. required: - status - meta properties: status: type: integer example: 200 meta: $ref: '#/components/schemas/Meta' ProductAuthenticated: description: | Authenticated (company-surface) Product read shape: the public `ProductBase` plus `custom_slug`, admin metadata never rendered on the public surface. allOf: - $ref: '#/components/schemas/ProductBase' - type: object properties: custom_slug: type: boolean description: | Authenticated-only. True when the merchant has pinned a permanent merchant-set slug; false when the slug is auto-generated from `title` and regenerates on rename. Rendered only on the company surface. example: false unevaluatedProperties: false UnauthorizedError: type: object description: | Bare 401 body — a single `message` string, not the wrapped `ErrorResponse`. required: - message properties: message: type: string example: Invalid credentials. ForbiddenError: description: | Bare 403 body: `{ error }` when a storefront permission is missing, or `{ message }` when the credential is not company-admin tier. oneOf: - type: object required: - error properties: error: type: string example: Not authorized. - type: object required: - message properties: message: type: string example: Not authorized. ErrorResponse: type: object required: - error - status - meta properties: error: type: object required: - message properties: message: type: string details: type: object additionalProperties: true status: type: integer meta: $ref: '#/components/schemas/Meta' Meta: type: object description: | Response metadata included on every successful response body. `request_id` and `timestamp` are always present; list endpoints also add `pagination`. required: - request_id - timestamp properties: request_id: type: - string - 'null' timestamp: type: string format: date-time pagination: $ref: '#/components/schemas/Pagination' ProductBase: type: object description: | Storefront Product. The first twelve fields are the canonical common top shared by every storefront resource in v202604 — same names, same order, same types across Categories, Collections, Products, Pages, Enrollment Packs, Posts, Media, Playlists. Product is the foundation's lone variant: it carries the shared common top but DELIBERATELY OMITS the `countries` array — a Product's geographic availability is variant-level, not a single access list. Instead the `country` query parameter drives the `pricing` block: it selects which variant's per-country price and currency are rendered. Product price is therefore COUNTRY-RELATIVE, not absolute (see the `pricing` field and the `country` parameter). Everything below `languages` is the Product-specific commerce tail: `sku`, `is_bundle`, `in_stock`, `has_subscription_plans`, `pricing`, `default_variant`, `variants`, `subscription_plans`, `media`, and `bundle_groups`. required: - id - slug - title - description - image_url - canonical_url - images - active - status - publish_at - seo - metafields - languages - sku - is_bundle - in_stock - has_subscription_plans - pricing - default_variant - variants - subscription_plans - media - bundle_groups properties: id: type: integer description: Unique identifier for the product. example: 60311 slug: type: - string - 'null' description: | URL-safe identifier, unique within the store; the public show resolves by this. Null for legacy products created without a slug (the column is nullable and friendly_id only backfills on write). example: scrute-farms-beet-blend title: type: string description: Human-readable product name shown in the storefront. example: Schrute Farms Beet Blend description: type: - string - 'null' description: >- Longer-form product copy. Null when the merchant set none. (Show payload only.) example: >- A cold-pressed beet concentrate from the finest acres on Schrute Farms. image_url: type: - string - 'null' description: >- Absolute URL of the product's primary image. Null when none. (Show payload only.) example: https://cdn.fluid.app/products/60311.png canonical_url: type: string description: >- Absolute canonical storefront URL for the product (the `/home/products/:slug` path). example: https://acme.fluid.app/home/products/scrute-farms-beet-blend images: $ref: '#/components/schemas/ResponsiveImageSet' description: >- Responsive ImageKit renditions (thumb/medium/large) of the primary image; null when none. active: type: boolean description: | Derived merchant on/off toggle: `true` when the product is not archived. When `false`, the product is hidden from EVERY public surface regardless of `status`. Unlike Category, Product has no standalone `active` column — it is computed from the `status` enum. example: true status: type: string enum: - draft - scheduled - published - archived description: | Lifecycle, mapped at read time from the Product's integer `status` enum (`active`/`draft`/`archived`) plus `publish_at`. The auto-go-live rule applies: an `active` product with a future `publish_at` resolves to `scheduled`; once `publish_at` passes (or is null) it resolves to `published`. "Live" = `active == true` AND resolved `status == published`. example: published publish_at: type: - string - 'null' format: date-time example: null seo: $ref: '#/components/schemas/Seo' metafields: type: array items: $ref: '#/components/schemas/Metafield' languages: type: array items: type: string description: | ISO codes of locales this product is translated into. Always includes the company default locale; never empty. example: - en - fr sku: type: - string - 'null' description: | The product-level stock-keeping unit. Null when the merchant tracks SKUs per variant only. example: SCRUTE-BEET-001 is_bundle: type: boolean description: | True when this product is a bundle assembled from bundle groups; its price is the configured bundle price, not a variant price. example: false in_stock: type: boolean description: | True when at least one variant is purchasable for some country. Mirrors the merchandising stock flag. example: true has_subscription_plans: type: boolean description: | True when the product has at least one active subscription plan, so the storefront can surface subscribe-and-save options. example: true pricing: type: - object - 'null' description: | COUNTRY-RELATIVE retail pricing for the requested `country` (defaults to the company's default country). The `country` query parameter selects which variant's per-country price and currency are rendered. Always the consumer-facing RETAIL price — never wholesale. `null` when the product has no resolvable price in any country. Bundle products price via the configured bundle price for the country. required: - price - currency_code - compare_at - subscription_price - display_price properties: price: type: - string - 'null' description: >- Numeric retail unit price in the country's currency, serialized as a decimal string. example: '29.99' currency_code: type: - string - 'null' description: ISO 4217 currency code for the resolved country. example: USD compare_at: type: - string - 'null' description: | Strike-through "compare at" price when the merchant set one, serialized as a decimal string; null otherwise. Always null for bundle products. example: '39.99' subscription_price: type: - string - 'null' description: | Per-cycle subscription price when the product has a subscription plan, serialized as a decimal string; null otherwise. Always null for bundle products. example: '26.99' display_price: type: - string - 'null' description: | Pre-formatted, currency-symbol price string ready to render in the storefront. example: $29.99 default_variant: type: - object - 'null' description: | Lightweight master-variant summary (id + sku). The full variant payload is in `variants`. Null when the product has no master variant. required: - id - sku properties: id: type: integer example: 880912 sku: type: - string - 'null' example: SCRUTE-BEET-001-12OZ variants: type: array description: | Every variant ordered by position, each rendered at the retail pricing tier. Per-country prices are keyed by ISO under `variant_countries`. items: $ref: '#/components/schemas/ProductVariant' subscription_plans: type: array description: | Active subscription plans available for this product, each wrapped with its default/active join metadata. The nested `subscription_plan` is priced against the requested country's variant at the retail tier. items: type: object required: - id - default - active - subscription_plan properties: id: type: integer description: The product_subscription_plan join-row id. example: 7741 default: type: boolean description: True when this is the product's default plan. example: true active: type: boolean description: True when the plan is active for this product. example: true subscription_plan: $ref: '#/components/schemas/SubscriptionPlan' media: type: array description: | Media attached to the product (videos, documents) ordered by priority. items: $ref: '#/components/schemas/ProductMedium' bundle_groups: type: array description: | Bundle groups defining the selectable items for a bundle product. Empty for non-bundle products. items: $ref: '#/components/schemas/ProductBundleGroup' Pagination: type: object required: - cursor - limit - prev_cursor - next_cursor properties: cursor: type: - string - 'null' limit: type: integer example: 25 prev_cursor: type: - string - 'null' next_cursor: type: - string - 'null' ResponsiveImageSet: type: - object - 'null' description: | Three ImageKit-transformed renditions of the resource's primary image: 200/600/1200 wide, scale-down only, format auto-negotiated. `null` when the resource has no image. properties: thumb: $ref: '#/components/schemas/ImageRendition' medium: $ref: '#/components/schemas/ImageRendition' large: $ref: '#/components/schemas/ImageRendition' Seo: type: object description: > Render-ready search-engine optimization metadata. ALWAYS present on every storefront response — never null. Values are resolved server-side via this priority chain: - `title` SEO title → resource title → company name - `description` SEO desc → resource desc → company default → "Live Free." - `image_url` SEO image → resource og_image → resource image → company default → hardcoded - `block_crawler` SEO block_crawler (false when no SEO row) Frontends, AEO crawlers, and SDKs can render directly from these values — no client-side fallback logic, no chance of HTML and JSON API drifting. `id` is exposed only on the authenticated surface and distinguishes a merchant-configured SEO row from inherited defaults. required: - title - description - image_url - block_crawler properties: title: type: string example: Summer Sale — Up to 40% Off description: Resolved title. Never null. description: type: string example: Shop the July clearance event before it ends. description: Resolved description. Never null. image_url: type: string example: >- https://ik.imagekit.io/fluidapp/tr:w-1200,h-630,c-maintain_ratio,fo-auto,f-auto,q-80/seo/9215.png description: Resolved OG-ready 1200×630 image URL. Never null. block_crawler: type: boolean example: false description: When true, the resource page emits a noindex meta tag. id: type: - integer - 'null' example: 9215 description: >- Authenticated-only. SearchEngineOptimizer row id when one exists; null when the values are inherited from the resource / company / hardcoded defaults. Metafield: type: object required: - namespace - key - value - value_type properties: namespace: type: string example: custom key: type: string example: material value: example: cotton value_type: type: string example: single_line_text_field description: type: - string - 'null' example: The primary material used in this product created_at: type: string format: date-time example: '2026-05-01T12:00:00Z' updated_at: type: string format: date-time example: '2026-05-01T12:00:00Z' locked: type: - boolean - 'null' example: false ProductVariant: type: object description: | A single purchasable Product variant, rendered at the retail pricing tier. Per-country retail pricing lives under `variant_countries`, keyed by ISO-2 country code. (The v202604 storefront surface is retail-only; wholesale and preferred-customer fields are not exposed here.) properties: id: type: integer description: Unique identifier for the variant. example: 880912 sku: type: - string - 'null' description: >- Stock-keeping unit for this variant. Null when the variant has no SKU. example: SCRUTE-BEET-001-12OZ is_master: type: boolean description: >- True when this is the product's master (default) variant — the one used for single-variant products and as the fallback selection. example: true title: type: - string - 'null' description: >- Short variant name, typically the option combination (e.g. "12 oz"). Null for a product with no distinct variant options. example: 12 oz display_name: type: - string - 'null' description: >- Full human-readable name combining the product title and this variant's options, ready to show in a cart or order line. example: Schrute Farms Beet Blend — 12 oz image_url: type: - string - 'null' description: >- Absolute URL of the variant's own primary image. Null when the variant inherits the product-level image. example: https://cdn.fluid.app/variants/880912.png position: type: - integer - 'null' description: Sort order of this variant within the product. Null when unset. example: 1 subscription_only: type: boolean description: >- True when this variant can ONLY be purchased as a subscription — one-time (single) purchase is not offered. example: false shipping_included_in_price: type: boolean description: >- True when shipping is already bundled into the price, so no separate shipping charge is applied at checkout. example: false track_quantity: type: boolean description: >- True when inventory is tracked for this variant (stock counts are enforced). When false, the variant is always purchasable. example: true inventory_quantity: type: - integer - 'null' description: >- Total sellable units on hand across all warehouses. Null when `track_quantity` is false (inventory is not counted). example: 142 bar_code: type: - string - 'null' description: Barcode / UPC / EAN for the variant. Null when unset. example: '0079827230015' keep_selling: type: boolean description: >- True when the variant stays purchasable after stock reaches zero (overselling/back-order allowed); false stops sales at zero stock. example: false limit_subscription: type: boolean description: >- True when the quantity per subscription order is capped (see `subscription_max_qty`). example: false subscription_max_qty: type: - integer - 'null' description: >- Maximum quantity allowed on a single subscription order when `limit_subscription` is true. Null when uncapped. example: null limit_quantity_per_customer: type: boolean description: >- True when a per-customer purchase limit applies to this variant (see `customer_limit`). example: false customer_limit: type: - integer - 'null' description: >- Maximum quantity a single customer may purchase when `limit_quantity_per_customer` is true. Null when unlimited. example: null option_attrs: type: array description: >- Human-readable option values that define this variant (e.g. size, flavor), in option order. items: type: string example: - 12 oz option_ids: type: array description: >- IDs of the option values that define this variant (parallel to `option_attrs`). items: type: integer example: - 4471 allow_subscription: type: boolean description: >- True when at least one active subscription plan is available for this variant. example: true images: type: array description: The variant's images, ordered by `position`. items: type: object properties: id: type: integer description: Image identifier. example: 5521 image_url: type: string description: Absolute, render-ready URL of the image. example: https://cdn.fluid.app/variants/880912/front.png image_path: type: - string - 'null' description: >- Raw storage path behind `image_url`, for clients applying their own ImageKit transforms. example: variants/880912/front.png position: type: integer description: Sort order of the image within the variant. example: 1 inventory_levels: type: array description: Per-warehouse stock breakdown for this variant. items: type: object properties: id: type: integer description: Inventory-level row identifier. example: 33019 available: type: integer description: >- Units sellable right now — `on_hand` minus `committed` minus `unavailable`. This is the number a storefront should treat as buyable. example: 142 committed: type: integer description: Units reserved by open (placed but unfulfilled) orders. example: 3 on_hand: type: integer description: >- Physical units present in the warehouse, regardless of reservation. example: 145 unavailable: type: integer description: >- On-hand units that cannot be sold (e.g. damaged, on quality hold, or otherwise reserved out of sale). example: 0 warehouse: type: object description: The warehouse this stock level belongs to. properties: id: type: integer description: Warehouse identifier. example: 12 name: type: string description: Human-readable warehouse name. example: Scranton DC active: type: boolean description: True when the warehouse is actively fulfilling orders. example: true country_iso: type: string description: ISO-2 country code the warehouse ships from. example: US variant_countries: type: object description: > Per-country RETAIL pricing keyed by ISO-2 country code. Each entry carries the consumer-facing price, currency, volumes, and display strings for that country — this is where the COUNTRY-RELATIVE pricing lives. The top-level `pricing` block is the resolved view for the single requested `country`. Wholesale and preferred-customer values are not exposed on this surface. additionalProperties: type: object properties: id: type: integer description: VariantCountry row identifier. example: 451233 active: type: boolean description: True when this variant is available for sale in this country. example: true country_id: type: integer description: Internal identifier of the country. example: 233 country_name: type: string description: Human-readable country name. example: United States currency_code: type: string description: >- ISO 4217 currency code the prices in this entry are denominated in. example: USD price: type: string description: >- Retail unit price in this country's currency, serialized as a decimal string. example: '29.99' compare_price: type: - string - 'null' description: >- Strike-through "compare at" reference price when the merchant set one, serialized as a decimal string; null otherwise. example: '39.99' subscription_price: type: - string - 'null' description: >- Per-cycle retail price when bought on subscription, serialized as a decimal string; null when the variant has no subscription pricing. example: '26.99' cv: type: string format: decimal description: >- Commissionable Volume (CV) — the volume credited for this item that counts toward commission calculations. example: '20' qv: type: string format: decimal description: >- Qualifying Volume (QV) — the volume credited for this item that counts toward rank and qualification requirements. example: '20' points: type: integer description: >- Points the buyer accumulates on an order for purchasing this item (per unit). example: 100 shipping: type: string description: >- Flat per-unit shipping cost for this country, in the entry's currency, serialized as a decimal string. example: '4.99' shipping_time: type: - string - 'null' description: >- Human-readable estimated delivery window for this country. Null when unset. example: 3–5 business days display_price: type: string description: Pre-formatted, currency-symbol price string ready to render. example: $29.99 display_subscription_price: type: string description: Pre-formatted subscription price string ready to render. example: $26.99 buyable: type: boolean description: >- True when a shopper can purchase this variant in this country right now (active and, if tracked, in stock). example: true subscription_plans: type: array description: >- Retail subscription pricing for this country, one entry per active plan on the product. items: type: object properties: id: type: integer description: Subscription plan identifier. example: 4410 subscription_price_in_currency: type: string description: >- Pre-formatted per-cycle subscription price for this plan. example: '26.99' subscribe_and_save_in_currency: type: string description: >- Pre-formatted amount saved per cycle vs. the one-time price. example: '3.00' subscribe_and_save_for_display: type: string description: Localized "subscribe and save" marketing string. example: Subscribe and save $3.00 metafields: type: array description: Custom metafields attached to the variant. items: type: object properties: namespace: type: string description: Grouping namespace for the metafield. example: custom key: type: string description: Metafield key, unique within its namespace. example: harvest_acre value: description: The metafield value (type per `value_type`). example: North Forty value_type: type: string description: The metafield's data type. example: single_line_text_field SubscriptionPlan: type: object description: | A subscription plan, rendered in the product_subscription_plan view (priced against the requested country's variant at the retail tier). properties: id: type: integer example: 4410 name: type: string example: Monthly Beet Club billing_interval: type: integer example: 1 billing_interval_unit: type: string enum: - day - week - month - year example: month billing_frequency_in_words: type: string example: Every month volume_interval: type: integer example: 1 volume_interval_unit: type: string enum: - day - week - month - year example: month allow_max_billing_cycles: type: boolean example: false max_billing_cycles: type: - integer - 'null' example: null price_adjustment_type: type: string example: percentage price_adjustment_amount: type: - string - 'null' example: '10.0' savings_display_mode: type: string example: percent active: type: boolean example: true subscription_price: type: - string - 'null' description: | Pre-formatted per-cycle subscription price for the requested country's variant at the retail tier. example: $26.99 savings_label: type: - string - 'null' example: Subscribe & save 10% ProductMedium: type: object description: A media item (video, document) attached to the product. properties: id: type: integer example: 99021 slug: type: string example: how-to-press-beets title: type: string example: How To Press Beets kind: type: - string - 'null' example: video media_type: type: - string - 'null' example: video media_format: type: - string - 'null' example: mp4 image_url: type: - string - 'null' example: https://cdn.fluid.app/media/99021/poster.png video_url: type: - string - 'null' example: https://cdn.fluid.app/media/99021/clip.mp4 canonical_url: type: string example: https://acme.fluid.app/home/media/how-to-press-beets description: type: - string - 'null' example: A two-minute walkthrough of the cold-press process. duration: type: - integer - 'null' example: 124 active: type: boolean example: true ProductBundleGroup: type: object description: | A bundle group defining selectable items for a bundle product. Present only on bundle products. properties: id: type: integer example: 3301 title: type: string example: Pick Your Beets description: type: - string - 'null' example: Choose any three jars for your bundle. group_type: type: - string - 'null' example: selectable min_selections: type: - integer - 'null' example: 1 max_selections: type: - integer - 'null' example: 3 selection_type: type: - string - 'null' example: multiple allow_subscriptions: type: boolean example: true force_subscriptions: type: boolean example: false sort_order: type: - integer - 'null' example: 1 bundle_group_items: type: array items: type: object properties: id: type: integer example: 71002 bundled_variant_id: type: - integer - 'null' example: 880912 quantity: type: - integer - 'null' example: 1 ImageRendition: type: object required: - url - width properties: url: type: string example: >- https://ik.imagekit.io/fluidapp/tr:w-600,c-at_max,f-auto,q-75/categories/4821.png width: type: integer example: 600 responses: Unauthorized: description: | Missing or invalid bearer token. The body is a bare `{ message }` object — not the wrapped `ErrorResponse` envelope used by 404 / 422. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' Forbidden: description: | Authenticated but lacking the required permission. The body is bare — `{ error }` when the storefront permission is missing, or `{ message }` when the credential is not company-admin tier — not the wrapped `ErrorResponse` envelope used by 404 / 422. content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: bearer_auth: type: http scheme: bearer description: | Bearer token authentication. Accepts company-admin tokens with `storefront.view` for read operations and `storefront.update` for writes and scan triggers (legacy per-resource grants like `categories.update` / `products.view` / etc. are still accepted during the migration), required on every `company` operation. Storefront public operations under `/api/v202604/{resource}` and `/api/v202604/{resource}/{slug}` are unauthenticated (`security: []`). ````