# Fluid

> ## 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 <token>; 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.

## Docs

- [Retrieve affiliate information](https://docs.fluid.app/api-reference/affiliate/retrieve-affiliate-information.md)
- [Validate an Apple Pay merchant session](https://docs.fluid.app/api-reference/apple-pay/validate-an-apple-pay-merchant-session.md): Requests a merchant session from Apple's startSession endpoint on behalf of the storefront domain. Requires a Referer header matching a verified domain.
- [Create auth token](https://docs.fluid.app/api-reference/auth-token/create-auth-token.md): Generate a short-lived authentication token for the current user company.
- [Confirm MFA passcode](https://docs.fluid.app/api-reference/authentication/confirm-mfa-passcode.md): Verify a multi-factor authentication code and receive JWTs for the user's companies.
- [Fetch company details from Fluid Shop name](https://docs.fluid.app/api-reference/authentication/fetch-company-details-from-fluid-shop-name.md): Public endpoint that returns basic company details by shop name. No authentication required.
- [Fetch user details from JWT](https://docs.fluid.app/api-reference/authentication/fetch-user-details-from-jwt.md): Decode a JWT and return the user and user-company profile information.
- [Resend MFA code via email](https://docs.fluid.app/api-reference/authentication/resend-mfa-code-via-email.md): Destroy the previous MFA record and create a new one, sending a fresh verification code.
- [Send MFA passcode](https://docs.fluid.app/api-reference/authentication/send-mfa-passcode.md): Send a multi-factor authentication passcode via email. Returns a generic success response even for unknown emails to prevent email enumeration.
- [Switch company](https://docs.fluid.app/api-reference/authentication/switch-company.md): Switch the authenticated user to a different company they belong to.
- [Authorize a Braintree transaction](https://docs.fluid.app/api-reference/braintree/authorize-a-braintree-transaction.md): Authorizes a Braintree transaction from a JS SDK nonce and stores the vault context on the cart. PaymentMethod creation happens via the payment_method endpoint afterwards.
- [Get Braintree client token](https://docs.fluid.app/api-reference/braintree/get-braintree-client-token.md): Returns the Braintree client token the browser uses to initialize the Braintree JS SDK for this cart, scoped to the Braintree `PaymentAccount` named by `payment_account_id`; `paypal_enabled` reports whether PayPal funding is available through that account. Cart-token authenticated. Returns `422` whe…
- [List callback definitions](https://docs.fluid.app/api-reference/callback-definitions/list-callback-definitions.md): Lists the callback definitions available to the company — the catalog of synchronous callbacks (e.g. tax, shipping) that a registration can target. Read-only. Requires a company Bearer token; returns `401` when the token is missing or invalid.
- [Create a callback registration](https://docs.fluid.app/api-reference/callback-registrations/create-a-callback-registration.md): Registers a synchronous callback for the company against a callback definition, so Fluid can call the given `url` for decisions such as tax or shipping. `definition_name` and `url` are required. Returns `201` with the created registration; `422` when the body fails validation; `409` when a registrat…
- [Delete a callback registration](https://docs.fluid.app/api-reference/callback-registrations/delete-a-callback-registration.md): Deletes a callback registration by its `uuid`; Fluid stops calling its `url`. Returns `200` echoing the deleted registration's `uuid`, or `404` when the uuid is unknown. Requires a company Bearer token (`401` otherwise).
- [List callback registrations](https://docs.fluid.app/api-reference/callback-registrations/list-callback-registrations.md): Lists the company's callback registrations, paginated. Read-only. Accepts an optional `filters` object (`page`/`per_page`, plus `company_id`, `definition_name`, `sorted_by`, and `active`). Requires a company Bearer token (`401` otherwise).
- [Show a callback registration](https://docs.fluid.app/api-reference/callback-registrations/show-a-callback-registration.md): Fetches a single callback registration by its `uuid`. Read-only. Returns `404` when no registration with that uuid belongs to the company. Requires a company Bearer token (`401` otherwise).
- [Update a callback registration](https://docs.fluid.app/api-reference/callback-registrations/update-a-callback-registration.md): Updates a callback registration's `url`, `active`, and `country_codes`; `definition_name` is fixed at creation. Returns `200` with the updated registration, `404` when the uuid is unknown, and `422` when the body fails validation. Requires a company Bearer token (`401` otherwise).
- [List callback schemas](https://docs.fluid.app/api-reference/callback-schemas/list-callback-schemas.md): Lists the request and response schemas for every callback definition — use them to generate types or validate callback payloads. Read-only. Requires a company Bearer token (`401` otherwise).
- [Show a callback schema](https://docs.fluid.app/api-reference/callback-schemas/show-a-callback-schema.md): Returns the schema for a specific callback definition.
- [List cart countries and languages](https://docs.fluid.app/api-reference/cart-auth/list-cart-countries-and-languages.md): Public, cart-token–scoped. Despite the `/auth/me` path, this returns the cart's available `countries` and `languages` (`CheckoutCartAuthIdentityResponse`) — it does **not** return a customer identity or session. Authorization is by the `cart_token` in the path; no bearer token is required (a company…
- [Logout from cart](https://docs.fluid.app/api-reference/cart-auth/logout-from-cart.md): Public, cart-token–scoped. Ends the customer session associated with the cart and returns the updated cart auth state. Authorization is by the `cart_token` in the path; no bearer token is required. Returns `410` when the cart is a locked/authorized enrollment cart and `404` when the cart token is un…
- [Send magic link](https://docs.fluid.app/api-reference/cart-auth/send-magic-link.md): Public, cart-token–scoped. Sends a magic-link / MFA challenge to the customer's `email` and returns a challenge `uuid` (`201`) to submit to `POST …/auth/verify`. No bearer token is required. `fluid_shop` here is the company subdomain (e.g. `acme`). Set `lookup_only: true` for a returning-buyer probe…
- [Verify magic link](https://docs.fluid.app/api-reference/cart-auth/verify-magic-link.md): Public, cart-token–scoped. Confirms a magic-link challenge: submit the `uuid` returned by `POST …/auth/magic_link` together with the customer's `verification_code`. On success the customer is bound to the cart (`200`). The credential is the cart token plus the verification code — no bearer token is…
- [Apply discount code](https://docs.fluid.app/api-reference/cart-discount/apply-discount-code.md): Applies a discount code to the cart. Not idempotent — applying the same code twice returns an error.
- [Apply manual discount (admin only)](https://docs.fluid.app/api-reference/cart-discount/apply-manual-discount-admin-only.md): Creates a one-time manual discount and applies it to the cart. Requires admin authentication (root_or_admin? role). Manual discounts are single-use, require a reason, and are excluded from the promo code management UI.
- [List all discounts applied to a cart](https://docs.fluid.app/api-reference/cart-discount/list-all-discounts-applied-to-a-cart.md): Returns per-discount detail for all active discounts on a cart, including code, reason, type, defined value, and actual amount applied.
- [Remove discount code](https://docs.fluid.app/api-reference/cart-discount/remove-discount-code.md): Removes a previously applied discount code from the cart and recalculates totals. The `discount_code` to remove is required in the body. Access is scoped by the `cart_token` in the path — the endpoint itself does not require authentication. In Fluid's recommended server-side integration you send a c…
- [Add items to cart](https://docs.fluid.app/api-reference/cart-items/add-items-to-cart.md): Applies one or more line-item changes and recalculates totals (unless `perform_cart_calculations` is false). Use `variant_id` with a positive `quantity` to add or update a variant. Use `variant_id` or `cart_item_id` with `quantity: 0` to remove the matching existing line. Mark a line as a subscripti…
- [Remove a cart item](https://docs.fluid.app/api-reference/cart-items/remove-a-cart-item.md): Removes the line item identified by `{id}` from the cart and recalculates totals; returns the updated cart. Access is scoped by the `cart_token` in the path — the endpoint itself does not require authentication. In Fluid's recommended server-side integration you send a company bearer token (`Authori…
- [Update a cart item](https://docs.fluid.app/api-reference/cart-items/update-a-cart-item.md): Updates a single line item identified by `{id}` — change its `quantity` or `variant_id`, or toggle `subscription`/`subscription_plan_id`. PATCH semantics: only supplied keys change. Access is scoped by the `cart_token` in the path — the endpoint itself does not require authentication. In Fluid's rec…
- [Apply points](https://docs.fluid.app/api-reference/cart-points/apply-points.md): Applies loyalty points to the cart. Not idempotent — validates balance and generates idempotency key.
- [Remove points](https://docs.fluid.app/api-reference/cart-points/remove-points.md): Removes any loyalty points applied to the cart and recalculates the amount due. Access is scoped by the `cart_token` in the path — the endpoint itself does not require authentication. In Fluid's recommended server-side integration you send a company bearer token (`Authorization: Bearer <company_toke…
- [Add enrollment to existing cart](https://docs.fluid.app/api-reference/carts/add-enrollment-to-existing-cart.md): Creates the enrollment record for an enrollment-pack cart from the submitted form answers.
- [Adds items to cart](https://docs.fluid.app/api-reference/carts/adds-items-to-cart.md): Adds one or more variants — including dynamic bundles — to the cart.
- [Applies a discount to the cart](https://docs.fluid.app/api-reference/carts/applies-a-discount-to-the-cart.md): Applies a promo discount code to the cart and recalculates totals.
- [Change cart country](https://docs.fluid.app/api-reference/carts/change-cart-country.md): Changes the cart's country. This triggers cascading side effects: clears shipping address, removes invalid discounts, recalculates available methods.
- [Check Order Status check order status](https://docs.fluid.app/api-reference/carts/check-order-status-check-order-status.md)
- [Client Token client token](https://docs.fluid.app/api-reference/carts/client-token-client-token.md)
- [Complete checkout](https://docs.fluid.app/api-reference/carts/complete-checkout.md): Converts the cart into an order and returns it. Pass the payment reference as the `payment_uuid` query parameter and send an `Idempotency-Key` header so a retried request never places a second order. Access is scoped by the `cart_token` in the path — the endpoint itself does not require authenticati…
- [Completes cart checkout](https://docs.fluid.app/api-reference/carts/completes-cart-checkout.md): Submits the cart for payment and converts it to an order.
- [Confirm magic link for cart](https://docs.fluid.app/api-reference/carts/confirm-magic-link-for-cart.md): Confirms a magic-link code and attaches the authenticated customer to the cart.
- [Create a cart](https://docs.fluid.app/api-reference/carts/create-a-cart.md): Creates a checkout cart and returns it, including the `cart_token` that scopes every subsequent cart operation. Public — no bearer token is required; from here on the `cart_token` in the path is what identifies the anonymous cart. The body requires `fluid_shop` (the company subdomain, e.g. `acme` —…
- [Create dlocal](https://docs.fluid.app/api-reference/carts/create-dlocal.md): Receives signed dLocal payment lifecycle notifications. Returns 200 only after the notification is authenticated and processed.
- [Create magic link for cart](https://docs.fluid.app/api-reference/carts/create-magic-link-for-cart.md): Sends a magic-link login code to the cart email so the shopper can sign in during checkout.
- [Create Payment create payment](https://docs.fluid.app/api-reference/carts/create-payment-create-payment.md)
- [Create ppro](https://docs.fluid.app/api-reference/carts/create-ppro.md)
- [Creates a cart](https://docs.fluid.app/api-reference/carts/creates-a-cart.md): Create a cart. Items, attribution and enrollment_pack_id are optional. Buyer rep assignment follows this priority: 1. If JWT is provided, extracts user from JWT and assigns as the rep. 2. If session cookie is present, extracts user from session and assigns it as the rep. 3. If no authentication is p…
- [Ipn ipn](https://docs.fluid.app/api-reference/carts/ipn-ipn.md)
- [Recalculate cart totals](https://docs.fluid.app/api-reference/carts/recalculate-cart-totals.md): Forces a fresh recalculation of the cart's tax, shipping, discounts, and totals and returns the refreshed cart. Use it after out-of-band changes when the cached totals may be stale. Access is scoped by the `cart_token` in the path — the endpoint itself does not require authentication. In Fluid's rec…
- [Removes item from cart](https://docs.fluid.app/api-reference/carts/removes-item-from-cart.md): Removes a line item from the cart and recalculates totals.
- [Removes rep_buyer and customer for the cart](https://docs.fluid.app/api-reference/carts/removes-rep_buyer-and-customer-for-the-cart.md): Detaches the authenticated customer from the cart, leaving the cart itself intact.
- [Retrieves a cart](https://docs.fluid.app/api-reference/carts/retrieves-a-cart.md): Returns the full cart — items, totals, addresses, and available payment methods — for a cart token.
- [Retrieves cart company information](https://docs.fluid.app/api-reference/carts/retrieves-cart-company-information.md): Returns the cart's company and storefront context without the full cart payload.
- [Retrieves enroll for cart](https://docs.fluid.app/api-reference/carts/retrieves-enroll-for-cart.md): Returns the enrollment form and pack context for an enrollment-pack cart.
- [Select shipping method](https://docs.fluid.app/api-reference/carts/select-shipping-method.md): Selects a shipping method. Idempotent — selecting the same method again is a no-op.
- [Set cart address](https://docs.fluid.app/api-reference/carts/set-cart-address.md): Sets the shipping/billing address. Triggers full recalculation (tax, shipping, totals) and fires webhook.
- [Set volume rep](https://docs.fluid.app/api-reference/carts/set-volume-rep.md): Sets the volume rep for the cart and triggers full recalculation. Unlike the other cart endpoints, the `cart_token` alone is not sufficient here — a customer or company bearer token is also required, because the rep assignment is attributed to the authenticated identity. An unknown `cart_token` is r…
- [Sets cart payment method](https://docs.fluid.app/api-reference/carts/sets-cart-payment-method.md): Sets the payment method on the cart. The type path parameter determines which payment provider flow is used. The payment_method request body fields vary by type. An optional billing_address can be provided with any type. Note: apple_pay may return a CreditCardPaymentResponse (card flow) or a PayPalP…
- [Sets cart shipping method](https://docs.fluid.app/api-reference/carts/sets-cart-shipping-method.md): Selects one of the cart's quoted shipping methods and recalculates totals.
- [Shipping Address Change shipping address change](https://docs.fluid.app/api-reference/carts/shipping-address-change-shipping-address-change.md)
- [Shipping Method Change shipping method change](https://docs.fluid.app/api-reference/carts/shipping-method-change-shipping-method-change.md)
- [Show a cart](https://docs.fluid.app/api-reference/carts/show-a-cart.md): Returns the current cart — its line items, totals, selected and available shipping methods, addresses, and applied discounts. Read-only; no side effects. Access is scoped by the `cart_token` in the path — the endpoint itself does not require authentication. In Fluid's recommended server-side integra…
- [Subscribes a cart item](https://docs.fluid.app/api-reference/carts/subscribes-a-cart-item.md): Converts a one-time line item into a subscription on the given plan.
- [Sync customer data to cart](https://docs.fluid.app/api-reference/carts/sync-customer-data-to-cart.md): Re-syncs the authenticated customer's data (saved addresses, payment methods, profile) onto the cart. Unlike the other cart endpoints, the `cart_token` alone is not sufficient here — a customer or company bearer token is also required, because the endpoint copies that identity's saved data onto the…
- [Syncs cart with authenticated customer](https://docs.fluid.app/api-reference/carts/syncs-cart-with-authenticated-customer.md): Associates the cart with the authenticated customer. Called by frontend on cart page load when user is logged in.
- [Update cart attributes](https://docs.fluid.app/api-reference/carts/update-cart-attributes.md): Updates buyer-level attributes on the cart — `email`, `phone`, and the `email_marketing`/`sms_marketing` opt-ins — using PATCH semantics (only the keys you send change). Access is scoped by the `cart_token` in the path — the endpoint itself does not require authentication. In Fluid's recommended ser…
- [Update cart language](https://docs.fluid.app/api-reference/carts/update-cart-language.md): Sets the cart's content language from `language_iso` (an ISO language code, e.g. `en`). Access is scoped by the `cart_token` in the path — the endpoint itself does not require authentication. In Fluid's recommended server-side integration you send a company bearer token (`Authorization: Bearer <comp…
- [Update cart metadata](https://docs.fluid.app/api-reference/carts/update-cart-metadata.md): Merges caller-supplied `metadata` / `json_data` onto the cart; both are free-form JSON pockets with no fixed schema. Access is scoped by the `cart_token` in the path — the endpoint itself does not require authentication. In Fluid's recommended server-side integration you send a company bearer token…
- [Updates a cart](https://docs.fluid.app/api-reference/carts/updates-a-cart.md): Updates the cart email and phone; a blank email clears it and recalculates email-gated discounts.
- [Updates a cart item's variant](https://docs.fluid.app/api-reference/carts/updates-a-cart-items-variant.md): Updates a cart item to use a different variant. If the target variant already exists in another cart item, the quantities are consolidated.
- [Updates cart address](https://docs.fluid.app/api-reference/carts/updates-cart-address.md): Sets the cart's ship-to or bill-to address and recalculates shipping and tax.
- [Updates subscribe:false to cart item](https://docs.fluid.app/api-reference/carts/updates-subscribe:false-to-cart-item.md): Converts a subscription line item back to a one-time purchase.
- [Updates the country of a cart, also updates the currency code](https://docs.fluid.app/api-reference/carts/updates-the-country-of-a-cart-also-updates-the-currency-code.md): Sets the cart's country, which re-prices items and refreshes shipping and tax.
- [Updates the language of a cart](https://docs.fluid.app/api-reference/carts/updates-the-language-of-a-cart.md): Sets the cart language, which drives translated product and pack copy on later responses.
- [Record a checkout starting](https://docs.fluid.app/api-reference/checkout/record-a-checkout-starting.md)
- [Update cart items prices](https://docs.fluid.app/api-reference/commerce/update-cart-items-prices.md): Overrides line-item prices on the cart. Used by admin tooling; requires a bearer token.
- [Create company event](https://docs.fluid.app/api-reference/company-events/create-company-event.md): Add a new event for the company with details like title, dates, venue, and optional media content.
- [Delete company event](https://docs.fluid.app/api-reference/company-events/delete-company-event.md): Deletes a specific event associated with the company.
- [Get company event](https://docs.fluid.app/api-reference/company-events/get-company-event.md): Retrieves the details of a specific event for a company.
- [List company events](https://docs.fluid.app/api-reference/company-events/list-company-events.md): Retrieves a list of events associated with the company.
- [Send event notifications](https://docs.fluid.app/api-reference/company-events/send-event-notifications.md): Sends notifications about an event to concerned parties based on specified countries.
- [Update company event](https://docs.fluid.app/api-reference/company-events/update-company-event.md): Updates the details of a specific company event.
- [Clone a Page](https://docs.fluid.app/api-reference/company/clone-a-page.md): Token-authenticated; requires `storefront.update`. Deep-copies the page together with its theme template. The clone lands unpublished (`draft`) with a fresh auto-generated slug and title suffix, and fires the `pages.created` webhook.
- [Company Categories index](https://docs.fluid.app/api-reference/company/company-categories-index.md): Token-authenticated. Returns EVERY Category for the calling company regardless of lifecycle (draft / scheduled / archived rows included), so admins can manage non-public rows.
- [Company Category show](https://docs.fluid.app/api-reference/company/company-category-show.md): Token-authenticated; resolves by id (the canonical company identifier). Returns any Category regardless of lifecycle.
- [Company Collection show](https://docs.fluid.app/api-reference/company/company-collection-show.md): Token-authenticated; resolves by id. Returns any Collection regardless of lifecycle.
- [Company Collections index](https://docs.fluid.app/api-reference/company/company-collections-index.md): Token-authenticated; returns every Collection regardless of lifecycle (admins manage drafts / scheduled / archived rows). Accepts the same params as the public catalog, plus the admin filters `filter[status]` and `filter[active]`.
- [Company Enrollment Pack show](https://docs.fluid.app/api-reference/company/company-enrollment-pack-show.md): Token-authenticated; resolves by id (the canonical company identifier). Returns the Enrollment Pack in any lifecycle state.
- [Company Enrollment Packs index](https://docs.fluid.app/api-reference/company/company-enrollment-packs-index.md): Token-authenticated; requires `storefront.view` (legacy `enrollment_packs.view` accepted during the migration). Returns EVERY pack for the calling company regardless of lifecycle, so admins can manage inactive (draft) rows. Same cursor / filter / sort / `q` contract as the public catalog; adds `filt…
- [Company Media index](https://docs.fluid.app/api-reference/company/company-media-index.md): Token-authenticated; requires `storefront.view` (legacy `media.view` accepted during the migration). Returns EVERY kept medium for the calling company regardless of lifecycle, so admins can manage draft / scheduled rows. Same cursor / filter / sort / `q` contract as the public catalog; adds `filter[…
- [Company Medium show](https://docs.fluid.app/api-reference/company/company-medium-show.md): Token-authenticated; resolves by id (the canonical company identifier). Returns the Medium in any lifecycle state.
- [Company Page show](https://docs.fluid.app/api-reference/company/company-page-show.md): Token-authenticated; resolves by id (the canonical company identifier). Returns the Page in any lifecycle state.
- [Company Pages index](https://docs.fluid.app/api-reference/company/company-pages-index.md): Token-authenticated; requires `storefront.view` (legacy `pages.view` accepted during the migration). Returns EVERY kept page for the calling company regardless of lifecycle, so admins can manage draft / scheduled rows. Same cursor / filter / sort / `q` contract as the public catalog; adds `filter[st…
- [Company Post show](https://docs.fluid.app/api-reference/company/company-post-show.md): Token-authenticated; resolves by id (the canonical company identifier). Returns the Post in any lifecycle state.
- [Company Posts index](https://docs.fluid.app/api-reference/company/company-posts-index.md): Token-authenticated; returns every Post regardless of lifecycle (admins manage drafts / scheduled / archived rows). Excludes discarded rows by default. Accepts the same params as the public catalog plus the admin-only `filter[status]` and `filter[active]`.
- [Company Product show](https://docs.fluid.app/api-reference/company/company-product-show.md): 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.
- [Company Products index](https://docs.fluid.app/api-reference/company/company-products-index.md): Token-authenticated. Returns EVERY Product for the calling company regardless of lifecycle (draft / archived rows included), so admins can manage non-public rows.
- [Create a Category](https://docs.fluid.app/api-reference/company/create-a-category.md): Token-authenticated; requires `storefront.update` (or legacy `categories.update` during the migration).
- [Create a Collection](https://docs.fluid.app/api-reference/company/create-a-collection.md): Token-authenticated; requires `storefront.update` (or legacy `collections.update` during the migration).
- [Create a Medium](https://docs.fluid.app/api-reference/company/create-a-medium.md): Token-authenticated; requires `storefront.update`. Triggers fresh Lighthouse + compliance scans automatically.
- [Create a Page](https://docs.fluid.app/api-reference/company/create-a-page.md): Token-authenticated; requires `storefront.update`. Triggers fresh Lighthouse + compliance scans automatically and fires the `pages.created` webhook. With `lang`, translated fields (`title`, `description`, `image_url`) are written for that locale.
- [Create a playlist](https://docs.fluid.app/api-reference/company/create-a-playlist.md): Creates a new playlist. `status: published` sets `active: true`; `status: draft` sets `active: false`. Send `slug` + `custom_slug: true` to pin a permanent slug; without `custom_slug: true` the slug regenerates on title change. After creation, Lighthouse and compliance scans are queued automatically…
- [Create a Post](https://docs.fluid.app/api-reference/company/create-a-post.md): Token-authenticated; requires `storefront.update` (or legacy `posts.update` during the migration).
- [Create a Product](https://docs.fluid.app/api-reference/company/create-a-product.md): Token-authenticated; requires `storefront.update` (or legacy `products.update` during the migration).
- [Create an Enrollment Pack](https://docs.fluid.app/api-reference/company/create-an-enrollment-pack.md): Token-authenticated; requires `storefront.update`. A pack must bundle at least one enrollable product. Triggers fresh Lighthouse + compliance scans automatically.
- [Destroy a Category](https://docs.fluid.app/api-reference/company/destroy-a-category.md): Token-authenticated. HARD-delete — Category does not use the Discard concern (the `archived` lifecycle state is the soft-deprecation path, not delete). Because categories form a tree, deleting one CASCADE-DESTROYS its descendant categories; products, media, and pages filed under it are unlinked (the…
- [Destroy a Collection](https://docs.fluid.app/api-reference/company/destroy-a-collection.md): Token-authenticated. HARD-delete — Collection does not yet use the Discard concern. Fires a `collections.deleted` webhook post-commit.
- [Destroy a Medium](https://docs.fluid.app/api-reference/company/destroy-a-medium.md): Token-authenticated. Soft-deletes via Discard (sets `discarded_at`).
- [Destroy a Page](https://docs.fluid.app/api-reference/company/destroy-a-page.md): Token-authenticated. Soft-deletes via Discard (sets `discarded_at`) and fires the `pages.deleted` webhook.
- [Destroy a Post (soft-delete)](https://docs.fluid.app/api-reference/company/destroy-a-post-soft-delete.md): Token-authenticated. SOFT-delete via Discard — sets `discarded_at`, does not hard-delete. The post is excluded from every public surface and the company index (kept-scope filter) but remains in the DB. Fires a `posts.deleted` webhook post-commit.
- [Destroy a Product](https://docs.fluid.app/api-reference/company/destroy-a-product.md): Token-authenticated. Soft-deletes the Product (Discard) and emits a `product.discarded` webhook post-commit so subscribers can react.
- [Destroy an Enrollment Pack](https://docs.fluid.app/api-reference/company/destroy-an-enrollment-pack.md): Token-authenticated. Soft-deletes via Discard (sets `discarded_at`) and detaches the pack from open carts.
- [Latest compliance result](https://docs.fluid.app/api-reference/company/latest-compliance-result.md): Returns the most recent compliance scan result for the Category. A fresh scan is queued automatically on every company create + update.
- [Latest compliance result](https://docs.fluid.app/api-reference/company/latest-compliance-result-1.md): Returns the most recent compliance scan result for the Product. A fresh scan is queued automatically on every company create + update.
- [Latest compliance result](https://docs.fluid.app/api-reference/company/latest-compliance-result-2.md): Returns the most recent compliance scan result for the Enrollment Pack. A fresh scan is queued automatically on every company create + update.
- [Latest compliance result](https://docs.fluid.app/api-reference/company/latest-compliance-result-3.md): Returns the most recent compliance scan result for the Post. A fresh scan is queued automatically on every company create + update.
- [Latest compliance result](https://docs.fluid.app/api-reference/company/latest-compliance-result-4.md): Returns the most recent compliance scan result for the Medium. A fresh scan is queued automatically on every company create + update.
- [Latest compliance result](https://docs.fluid.app/api-reference/company/latest-compliance-result-5.md): Returns the most recent compliance scan result for the Page. A fresh scan is queued automatically on every company create + update.
- [Latest compliance result](https://docs.fluid.app/api-reference/company/latest-compliance-result-6.md): Returns the most recent compliance scan result for the Collection. A fresh scan is queued automatically on every company create + update.
- [Latest compliance result for a playlist](https://docs.fluid.app/api-reference/company/latest-compliance-result-for-a-playlist.md): Returns the most recent compliance scan result for the playlist. A fresh scan is queued automatically on every company create + update.
- [Latest Lighthouse result](https://docs.fluid.app/api-reference/company/latest-lighthouse-result.md): Returns the most recent successful Lighthouse scan for the Category (scans persist only on success). A fresh scan is auto-queued on every company create and update, but it runs asynchronously — a failed, rate-limited, or recently-run rescan writes no new record, so this endpoint may return the prior…
- [Latest Lighthouse result](https://docs.fluid.app/api-reference/company/latest-lighthouse-result-1.md): Returns the most recent successful Lighthouse scan for the Product (scans persist only on success). A fresh scan is auto-queued on every company create and update, but it runs asynchronously — a failed, rate-limited, or recently-run rescan writes no new record, so this endpoint may return the prior…
- [Latest Lighthouse result](https://docs.fluid.app/api-reference/company/latest-lighthouse-result-2.md): Returns the most recent successful Lighthouse scan for the Enrollment Pack (scans persist only on success). A fresh scan is auto-queued on every company create and update, but it runs asynchronously — a failed, rate-limited, or recently-run rescan writes no new record, so this endpoint may return th…
- [Latest Lighthouse result](https://docs.fluid.app/api-reference/company/latest-lighthouse-result-3.md): Returns the most recent Lighthouse scan for the Post, including the full Lighthouse JSON `result` blob. When no scan exists, queues one and returns 202 with `scan_status`.
- [Latest Lighthouse result](https://docs.fluid.app/api-reference/company/latest-lighthouse-result-4.md): Returns the most recent successful Lighthouse scan for the Medium (scans persist only on success). A fresh scan is auto-queued on every company create and update, but it runs asynchronously — a failed, rate-limited, or recently-run rescan writes no new record, so this endpoint may return the prior s…
- [Latest Lighthouse result](https://docs.fluid.app/api-reference/company/latest-lighthouse-result-5.md): Returns the most recent successful Lighthouse scan for the Page (scans persist only on success). A fresh scan is auto-queued on every company create and update, but it runs asynchronously — a failed, rate-limited, or recently-run rescan writes no new record, so this endpoint may return the prior sca…
- [Latest Lighthouse result](https://docs.fluid.app/api-reference/company/latest-lighthouse-result-6.md): Returns the most recent Lighthouse scan for the Collection, including the full Lighthouse JSON `result` blob. When no scan exists, queues one and returns 202 with `scan_status`.
- [Latest Lighthouse result for a playlist](https://docs.fluid.app/api-reference/company/latest-lighthouse-result-for-a-playlist.md): Returns the most recent successful Lighthouse scan for the Playlist (scans persist only on success). A fresh scan is auto-queued on every company create and update, but it runs asynchronously — a failed, rate-limited, or recently-run rescan writes no new record, so this endpoint may return the prior…
- [List playlists (company, authenticated)](https://docs.fluid.app/api-reference/company/list-playlists-company-authenticated.md): Returns ALL company playlists regardless of lifecycle (including inactive/ draft). Use `filter[status]` or `filter[active]` to narrow. Auth required. After each create or update, both Lighthouse and compliance scans are queued automatically — a brief `scan_status: pending` on `GET :id/lighthouse` an…
- [Products in a Category](https://docs.fluid.app/api-reference/company/products-in-a-category.md): Every product filed under this category, including the draft and archived rows the public listing hides.
- [Products in a Collection](https://docs.fluid.app/api-reference/company/products-in-a-collection.md): Every product filed under this collection, including the draft and archived rows the public listing hides.
- [Share statistics for a Category](https://docs.fluid.app/api-reference/company/share-statistics-for-a-category.md): Read-only aggregate share stats. Same response shape across all seven storefront resources.
- [Share statistics for a Collection](https://docs.fluid.app/api-reference/company/share-statistics-for-a-collection.md): Read-only aggregate share stats. Same response shape every storefront resource returns from `GET :id/shares`.
- [Share statistics for a Medium](https://docs.fluid.app/api-reference/company/share-statistics-for-a-medium.md): Read-only aggregate share statistics for the Medium. Uses the shared shares response shape common to the storefront resources.
- [Share statistics for a Page](https://docs.fluid.app/api-reference/company/share-statistics-for-a-page.md): Read-only aggregate share statistics for the Page. Uses the shared shares response shape common to the storefront resources.
- [Share statistics for a playlist](https://docs.fluid.app/api-reference/company/share-statistics-for-a-playlist.md): Read-only aggregate share statistics for the playlist. Uses the shared shares response shape common to the storefront resources.
- [Share statistics for a Post](https://docs.fluid.app/api-reference/company/share-statistics-for-a-post.md): Read-only aggregate share statistics for the Post. Uses the shared shares response shape common to the storefront resources.
- [Share statistics for a Product](https://docs.fluid.app/api-reference/company/share-statistics-for-a-product.md): Read-only aggregate share stats. Same response shape across all seven storefront resources.
- [Share statistics for an Enrollment Pack](https://docs.fluid.app/api-reference/company/share-statistics-for-an-enrollment-pack.md): Read-only aggregate share statistics for the Enrollment Pack. Uses the shared shares response shape common to the storefront resources.
- [Show a playlist (company, by id)](https://docs.fluid.app/api-reference/company/show-a-playlist-company-by-id.md): With `lang`, translated fields (`title`, `description`) render in that locale — use it to read a specific translation before editing it.
- [Soft-delete a playlist](https://docs.fluid.app/api-reference/company/soft-delete-a-playlist.md): Soft-deletes (discards) the playlist. The slug becomes available for reuse immediately.
- [Trigger a compliance scan](https://docs.fluid.app/api-reference/company/trigger-a-compliance-scan.md): Queues a fresh compliance scan. Returns immediately with `202 Accepted`; the new result lands at `GET :id/compliance` when the job completes.
- [Trigger a compliance scan](https://docs.fluid.app/api-reference/company/trigger-a-compliance-scan-1.md): Queues a fresh compliance scan. Returns immediately with `202 Accepted`; the new result lands at `GET :id/compliance` when the job completes.
- [Trigger a compliance scan](https://docs.fluid.app/api-reference/company/trigger-a-compliance-scan-2.md): Queues a fresh compliance scan for the Enrollment Pack. Returns immediately with `202 Accepted`; the new result lands at `GET :id/compliance` once the job completes.
- [Trigger a compliance scan](https://docs.fluid.app/api-reference/company/trigger-a-compliance-scan-3.md): Queues a fresh compliance scan for the Post. Returns immediately with `202 Accepted`; the new result lands at `GET :id/compliance` once the job completes.
- [Trigger a compliance scan](https://docs.fluid.app/api-reference/company/trigger-a-compliance-scan-4.md): Queues a fresh compliance scan for the Medium. Returns immediately with `202 Accepted`; the new result lands at `GET :id/compliance` once the job completes.
- [Trigger a compliance scan](https://docs.fluid.app/api-reference/company/trigger-a-compliance-scan-5.md): Queues a fresh compliance scan for the Page. Returns immediately with `202 Accepted`; the new result lands at `GET :id/compliance` once the job completes.
- [Trigger a compliance scan](https://docs.fluid.app/api-reference/company/trigger-a-compliance-scan-6.md): Queues a fresh compliance scan. Returns immediately with `202 Accepted`; the new result lands at `GET :id/compliance` when the job completes.
- [Trigger a compliance scan for a playlist](https://docs.fluid.app/api-reference/company/trigger-a-compliance-scan-for-a-playlist.md): Queues a fresh compliance scan for the playlist. Returns immediately with `202 Accepted`; the new result lands at `GET :id/compliance` once the job completes.
- [Trigger a Lighthouse scan](https://docs.fluid.app/api-reference/company/trigger-a-lighthouse-scan.md): Queues a fresh Lighthouse scan. Returns immediately with `202 Accepted`; the new result lands at `GET :id/lighthouse` when the job completes (usually <60s).
- [Trigger a Lighthouse scan](https://docs.fluid.app/api-reference/company/trigger-a-lighthouse-scan-1.md): Queues a fresh Lighthouse scan. Returns immediately with `202 Accepted`; the new result lands at `GET :id/lighthouse` when the job completes (usually <60s).
- [Trigger a Lighthouse scan](https://docs.fluid.app/api-reference/company/trigger-a-lighthouse-scan-2.md): Queues a fresh Lighthouse scan for the Enrollment Pack. Returns immediately with `202 Accepted`; the new result lands at `GET :id/lighthouse` once the job completes. Manual triggers are rarely needed — every company create and update auto-queues a scan — but are useful when an out-of-band change (DN…
- [Trigger a Lighthouse scan](https://docs.fluid.app/api-reference/company/trigger-a-lighthouse-scan-3.md): Queues a fresh Lighthouse scan for the Post. Returns immediately with `202 Accepted`; the new result lands at `GET :id/lighthouse` once the job completes. Manual triggers are rarely needed — every company create and update auto-queues a scan — but are useful when an out-of-band change (DNS, CDN, the…
- [Trigger a Lighthouse scan](https://docs.fluid.app/api-reference/company/trigger-a-lighthouse-scan-4.md): Queues a fresh Lighthouse scan for the Medium. Returns immediately with `202 Accepted`; the new result lands at `GET :id/lighthouse` once the job completes. Manual triggers are rarely needed — every company create and update auto-queues a scan — but are useful when an out-of-band change (DNS, CDN, t…
- [Trigger a Lighthouse scan](https://docs.fluid.app/api-reference/company/trigger-a-lighthouse-scan-5.md): Queues a fresh Lighthouse scan for the Page. Returns immediately with `202 Accepted`; the new result lands at `GET :id/lighthouse` once the job completes. Manual triggers are rarely needed — every company create and update auto-queues a scan — but are useful when an out-of-band change (DNS, CDN, the…
- [Trigger a Lighthouse scan](https://docs.fluid.app/api-reference/company/trigger-a-lighthouse-scan-6.md): Queues a fresh Lighthouse scan. Returns immediately with `202 Accepted`; the new result lands at `GET :id/lighthouse` when the job completes.
- [Trigger a Lighthouse scan for a playlist](https://docs.fluid.app/api-reference/company/trigger-a-lighthouse-scan-for-a-playlist.md): Queues a fresh Lighthouse scan for the playlist. Returns immediately with `202 Accepted`; the new result lands at `GET :id/lighthouse` once the job completes. Manual triggers are rarely needed — every company create and update auto-queues a scan — but are useful when an out-of-band change (DNS, CDN,…
- [Update a Category](https://docs.fluid.app/api-reference/company/update-a-category.md): Token-authenticated. PATCH semantics — only keys present in the payload are updated.
- [Update a Collection](https://docs.fluid.app/api-reference/company/update-a-collection.md): Token-authenticated. PATCH semantics — only keys present in the payload are updated. Triggers fresh Lighthouse + compliance scans automatically.
- [Update a Medium](https://docs.fluid.app/api-reference/company/update-a-medium.md): Token-authenticated; requires `storefront.update`. Only the keys sent are updated. Triggers fresh Lighthouse + compliance scans.
- [Update a Page](https://docs.fluid.app/api-reference/company/update-a-page.md): Token-authenticated; requires `storefront.update`. Only the keys sent are updated. Triggers fresh Lighthouse + compliance scans and fires the `pages.updated` webhook. With `lang`, translated fields are written for that locale only.
- [Update a playlist](https://docs.fluid.app/api-reference/company/update-a-playlist.md): Partial update — only keys present in the payload are changed. After the update, Lighthouse and compliance scans are queued automatically. With `lang`, the translatable fields (`title`, `description`) are written for that locale only — the default-locale copy is untouched; omitting `lang` writes the…
- [Update a Post](https://docs.fluid.app/api-reference/company/update-a-post.md): Token-authenticated. PATCH semantics — only keys present in the payload are updated. Triggers fresh Lighthouse + compliance scans automatically.
- [Update a Product](https://docs.fluid.app/api-reference/company/update-a-product.md): Token-authenticated. PATCH semantics — only keys present in the payload are updated. On update `variant_countries_attributes` is OPTIONAL (a PATCH may touch a variant's scalars without resending its full per-country price matrix). Same nested write contract and `accepts_nested_attributes_for` key na…
- [Update an Enrollment Pack](https://docs.fluid.app/api-reference/company/update-an-enrollment-pack.md): Token-authenticated; requires `storefront.update`. Only the keys sent are updated. Triggers fresh Lighthouse + compliance scans.
- [Confirm visitor](https://docs.fluid.app/api-reference/confirm-visitor/confirm-visitor.md): Mark a visitor as confirmed using their secure token.
- [Apply address to subscriptions](https://docs.fluid.app/api-reference/customer-addresses/apply-address-to-subscriptions.md): Apply the specified address to the customer's subscriptions. Pass `apply_to_all: true` to update all subscriptions, or pass a `subscription_ids` array to update specific subscriptions only.
- [Create customer address](https://docs.fluid.app/api-reference/customer-addresses/create-customer-address.md): Saves a new address on the authenticated customer's account; the address fields are supplied under `address`. Requires a customer bearer token. Returns `422` on validation failure and `401` when unauthenticated.
- [Delete customer address](https://docs.fluid.app/api-reference/customer-addresses/delete-customer-address.md): Deletes the saved address identified by `{id}` from the authenticated customer's account. Requires a customer bearer token. Returns `404` when the address is not found, `422` when it cannot be removed, and `401` when unauthenticated.
- [List customer addresses](https://docs.fluid.app/api-reference/customer-addresses/list-customer-addresses.md): Lists the authenticated customer's saved addresses. Requires a customer bearer token; returns `401` when unauthenticated.
- [Update customer address](https://docs.fluid.app/api-reference/customer-addresses/update-customer-address.md): Updates the saved address identified by `{id}` (also passed as `address_id`) with the fields under `address`. Requires a customer bearer token. Returns `404` when the address is not found, `422` on validation failure, and `401` when unauthenticated.
- [List customer orders](https://docs.fluid.app/api-reference/customer-orders/list-customer-orders.md): Returns the authenticated customer's order history with cursor pagination.
- [Create customer payment method](https://docs.fluid.app/api-reference/customer-payment-methods/create-customer-payment-method.md): Saves a payment method on the authenticated customer's account. Requires `type`, `country_code`, and a `payment_method` payload; set `default_payment_method: true` to make it the default. Requires a customer bearer token. Returns `422` on validation or tokenization failure and `401` when unauthentic…
- [Delete customer payment method](https://docs.fluid.app/api-reference/customer-payment-methods/delete-customer-payment-method.md): Deletes the saved payment method identified by `{id}`. Requires a customer bearer token. Returns `404` when not found, `422` when it cannot be removed, and `401` when unauthenticated.
- [List customer payment methods](https://docs.fluid.app/api-reference/customer-payment-methods/list-customer-payment-methods.md): Lists the authenticated customer's saved payment methods. Requires a customer bearer token; returns `401` when unauthenticated.
- [Tokenize payment credentials](https://docs.fluid.app/api-reference/customer-payment-methods/tokenize-payment-credentials.md): Vaults payment credentials via VGS. Requires a valid customer JWT.
- [Update customer payment method](https://docs.fluid.app/api-reference/customer-payment-methods/update-customer-payment-method.md): Updates the saved payment method identified by `{id}` (also passed as `payment_method_id`) — e.g. set `set_as_default` or update its `billing_address`. Requires a customer bearer token. Returns `404` when not found, `422` on validation failure, and `401` when unauthenticated.
- [List customer points ledger](https://docs.fluid.app/api-reference/customer-points/list-customer-points-ledger.md): Returns the authenticated customer's points ledger with page pagination.
- [Get customer profile](https://docs.fluid.app/api-reference/customers/get-customer-profile.md): Returns the authenticated customer's profile. Requires a customer bearer token; returns `401` when the token is missing or invalid.
- [List customer companies](https://docs.fluid.app/api-reference/customers/list-customer-companies.md): Lists the companies the authenticated customer belongs to. Requires a customer bearer token; returns `401` when unauthenticated.
- [Update customer profile](https://docs.fluid.app/api-reference/customers/update-customer-profile.md): Updates the authenticated customer's profile (e.g. the linked `fluid_pay_account`). Requires a customer bearer token. Returns `401` when unauthenticated and `422` on validation failure.
- [List reps](https://docs.fluid.app/api-reference/directory/list-reps.md): Lists reps for the authenticated company.
- [List users](https://docs.fluid.app/api-reference/directory/list-users.md): Lists users for the authenticated company. Page paginated.
- [Get enrollment pack by slug](https://docs.fluid.app/api-reference/enrollment-packs/get-enrollment-pack-by-slug.md): Returns enrollment pack details including enrollable products with bundle group configuration for dynamic bundle products.
- [Show enrollment](https://docs.fluid.app/api-reference/enrollments/show-enrollment.md): Public endpoint — retrieves enrollment form by token.
- [Submit enrollment field answer](https://docs.fluid.app/api-reference/enrollments/submit-enrollment-field-answer.md): Submits an answer for the enrollment field `{field_id}` on the enrollment identified by `{token}`. Public — no bearer token is required; the enrollment `{token}` in the path scopes the request. Returns `404` when the enrollment or field is not found and `422` when the answer fails validation.
- [Update enrollment field answer](https://docs.fluid.app/api-reference/enrollments/update-enrollment-field-answer.md): Updates a previously submitted answer for the enrollment field `{field_id}` on the enrollment `{token}`. Public — no bearer token is required. Returns `404` when the enrollment or field is not found and `422` when the answer fails validation.
- [Upload file for enrollment field](https://docs.fluid.app/api-reference/enrollments/upload-file-for-enrollment-field.md): Uploads a file answer (the `file` part) for the enrollment field `{field_id}` on the enrollment `{token}`. Public — no bearer token is required. Returns `404` when the enrollment or field is not found and `422` when the upload fails validation.
- [Save a new lead capture](https://docs.fluid.app/api-reference/events/save-a-new-lead-capture.md)
- [Save a new page visit](https://docs.fluid.app/api-reference/events/save-a-new-page-visit.md)
- [Save a new url visit](https://docs.fluid.app/api-reference/events/save-a-new-url-visit.md)
- [Start a new fingerprint](https://docs.fluid.app/api-reference/fingerprint/start-a-new-fingerprint.md)
- [Get form by public token](https://docs.fluid.app/api-reference/forms/get-form-by-public-token.md)
- [Submit a form response](https://docs.fluid.app/api-reference/forms/submit-a-form-response.md)
- [Verify form password](https://docs.fluid.app/api-reference/forms/verify-form-password.md)
- [Create a gateway](https://docs.fluid.app/api-reference/gateways/create-a-gateway.md): Creates a new payment gateway for the authenticated merchant from the `gateway` payload. Returns `201` with the created gateway. `credentials` are write-only and never returned. Returns `422` when required fields are missing or `integration_type`/`mode` is invalid.
- [Create a purchase transaction](https://docs.fluid.app/api-reference/gateways/create-a-purchase-transaction.md): Charges the payment method immediately (authorize and capture in a single step) for `amount_cents` on the gateway. Creates a `purchase` transaction and returns it with `201`. Pass an `Idempotency-Key` header to make retries safe — a replay returns the original result with `X-Idempotent-Replayed: tru…
- [Create an authorization](https://docs.fluid.app/api-reference/gateways/create-an-authorization.md): Authorizes (holds funds on) the payment method for `amount_cents` without capturing. Creates an `authorize` transaction and returns it with `201`; capture it later via the transaction capture endpoint or release it with void. Pass an `Idempotency-Key` header to make retries safe. Returns `404` when…
- [Delete a gateway](https://docs.fluid.app/api-reference/gateways/delete-a-gateway.md): Deletes a gateway. Returns `204` with no body on success. Returns `404` when the gateway does not exist for the authenticated merchant.
- [Get a gateway](https://docs.fluid.app/api-reference/gateways/get-a-gateway.md): Retrieves a single gateway by slug, UUID, or numeric ID. Read-only; secret values in `settings` are obfuscated. Returns `404` when no gateway matches the identifier for the authenticated merchant.
- [List gateways](https://docs.fluid.app/api-reference/gateways/list-gateways.md): Lists the payment gateways configured for the authenticated merchant. Read-only; returns an empty `data` array when none are configured. Requires a valid API key or JWT bearer token (`401` if missing/invalid, `403` if the credential is not authorized).
- [Update a gateway](https://docs.fluid.app/api-reference/gateways/update-a-gateway.md): Updates an existing gateway. Only the fields present in the `gateway` payload are changed (PATCH semantics); omit `credentials` to preserve stored secrets. Returns `200` with the updated gateway. Returns `404` when the gateway does not exist and `422` on validation failure.
- [Verify a payment method ($0 auth)](https://docs.fluid.app/api-reference/gateways/verify-a-payment-method-$0-auth.md): Runs a zero-amount authorization to confirm a payment method is valid without charging it. Creates a `verify` transaction and returns it with `201`. The request body is optional. Returns `404` when the gateway is not found and `422` when the request fails validation.
- [Exit company impersonation](https://docs.fluid.app/api-reference/impersonation/exit-company-impersonation.md): Exit company impersonation and return to the original admin session.
- [Impersonate a company](https://docs.fluid.app/api-reference/impersonation/impersonate-a-company.md): Start impersonating a company. Only accessible by root admins.
- [Create a Klarna payment session](https://docs.fluid.app/api-reference/klarna/create-a-klarna-payment-session.md): Creates a Klarna payment session for the cart and returns the `session_id` and `client_token` used to render the Klarna widget client-side. The optional `intent` selects the Klarna session intent. Cart-token authenticated. Returns `400` when Klarna rejects the session, `404` when the cart is not fou…
- [Update a Klarna payment session](https://docs.fluid.app/api-reference/klarna/update-a-klarna-payment-session.md): Refreshes an existing Klarna session (identified by `session_id` in the body) against the cart's current line items and totals. Cart-token authenticated. Returns `400` when Klarna rejects the update, `404` when the cart is not found, `410` when the cart has already been processed, and `422` for inva…
- [Create video analytics event](https://docs.fluid.app/api-reference/media/create-video-analytics-event.md)
- [Get media by slug](https://docs.fluid.app/api-reference/media/get-media-by-slug.md)
- [Get media by slug (deprecated)](https://docs.fluid.app/api-reference/media/get-media-by-slug-deprecated.md)
- [Get merchant payment configuration](https://docs.fluid.app/api-reference/merchant-configuration/get-merchant-payment-configuration.md): Root-admin-only. Returns VGS, Kount, 3DS acquirer, payout, and platform-fee settings for a merchant. Secret fields are obfuscated.
- [Update merchant payment configuration](https://docs.fluid.app/api-reference/merchant-configuration/update-merchant-payment-configuration.md): Root-admin-only. Updates VGS, Kount, 3DS acquirer, payout, and/or platform-fee settings. Obfuscated secret values (containing "********") are silently skipped to prevent overwriting real secrets. 3DS acquirer fields are merged into the network_3ds_setting JSONB. Payout fields are merged into payouts…
- [Create a multi-factor authentication](https://docs.fluid.app/api-reference/multi-factor-authentications/create-a-multi-factor-authentication.md): Create a new MFA record and send a verification code via the specified channel.
- [Verify a multi-factor authentication code](https://docs.fluid.app/api-reference/multi-factor-authentications/verify-a-multi-factor-authentication-code.md): Submit a verification code to authenticate an MFA record.
- [Atomically apply one or more edits to an existing order](https://docs.fluid.app/api-reference/order_edits/atomically-apply-one-or-more-edits-to-an-existing-order.md): Inserts items and / or adds general-purpose adjustments to an order in a single DB transaction. After the operations run, the eight `current_*` totals on the order are recalculated and an order-edit audit record is written per operation.
- [Dry-run an edit and return the would-be order shape](https://docs.fluid.app/api-reference/order_edits/dry-run-an-edit-and-return-the-would-be-order-shape.md): Accepts the same payload as POST /api/v202604/orders/{order_id}/edits. Runs the operations through the same editing engine as the commit endpoint inside a database savepoint that is ALWAYS rolled back, then returns the order with its recalculated `current_*` totals reflecting the post-operation stat…
- [Retrieves an order with points redemption](https://docs.fluid.app/api-reference/orders/retrieves-an-order-with-points-redemption.md)
- [Show order](https://docs.fluid.app/api-reference/orders/show-order.md): Public endpoint — no authentication required. Retrieves an order by token.
- [Creates a Klarna payment session](https://docs.fluid.app/api-reference/payment/creates-a-klarna-payment-session.md)
- [Updates a Klarna session](https://docs.fluid.app/api-reference/payment/updates-a-klarna-session.md)
- [Initialize 3DS verification](https://docs.fluid.app/api-reference/payments/initialize-3ds-verification.md): Starts 3D Secure device fingerprinting for the cart's payment method and returns the 3DS method content and the merchant transaction id for the attempt. This is the `requires_3ds` branch of the card payment flow (see `tokenize`): completing it authorizes the card and yields the Fluid payment referen…
- [Provision VGS vault credentials](https://docs.fluid.app/api-reference/payments/provision-vgs-vault-credentials.md): Resolves the CreditCard payment account for the cart, pins the routing decision on the cart, and returns the VGS Collect vault credentials used to tokenize card data client-side. No request body. This begins the card payment flow: after tokenizing the card (and completing 3D Secure via `verify` when…
- [Set the cart payment method](https://docs.fluid.app/api-reference/payments/set-the-cart-payment-method.md): Sets the payment method on the cart (idempotent). The request and response shapes vary by payment type. The declared contract requires type; the saved-payment-method flow (payment_method_id) is the only flow that may omit payment_method.
- [Apply a PayPal shipping address change](https://docs.fluid.app/api-reference/paypal/apply-a-paypal-shipping-address-change.md): Updates the cart's shipping (and mirrored billing) address from the PayPal onShippingChange callback, recalculates the cart, and patches the PayPal order.
- [Authorize a PayPal order](https://docs.fluid.app/api-reference/paypal/authorize-a-paypal-order.md): Authorizes a previously created PayPal order (identified by `order_id` in the body) and returns its `authorization_id`. Cart-token authenticated. Returns `400` when the order id is invalid, `404` when the cart is not found, `410` when the cart has already been processed, and `422` for invalid parame…
- [Authorize order in paypal](https://docs.fluid.app/api-reference/paypal/authorize-order-in-paypal.md)
- [Create a PayPal order](https://docs.fluid.app/api-reference/paypal/create-a-paypal-order.md): Creates a PayPal order for the cart and returns its `order_id` for the client SDK to approve. Supplying `payment_token_id` switches the request to the Fastlane capture flow, which additionally returns `authorization_id` and a `payment_uuid` — the Fluid payment reference carried into the Cart checkou…
- [Create order in paypal](https://docs.fluid.app/api-reference/paypal/create-order-in-paypal.md)
- [Get PayPal client SDK token](https://docs.fluid.app/api-reference/paypal/get-paypal-client-sdk-token.md): Returns the PayPal client SDK token the browser uses to initialize the PayPal JS SDK for this cart. The token is scoped to the PayPal `PaymentAccount` named by `payment_account_id`. Cart-token authenticated (the token in the path is the credential; no bearer token). Returns `422` when `payment_accou…
- [Get playlist by slug](https://docs.fluid.app/api-reference/playlist/get-playlist-by-slug.md)
- [Get playlist by slug (deprecated)](https://docs.fluid.app/api-reference/playlist/get-playlist-by-slug-deprecated.md)
- [Get product by slug in a foreign local includes the correct variants](https://docs.fluid.app/api-reference/product/get-product-by-slug-in-a-foreign-local-includes-the-correct-variants.md)
- [Query product](https://docs.fluid.app/api-reference/products/query-product.md): Returns a single product and its purchasable variants for the checkout surface. `{id}` accepts a product id or slug. Uses POST because the request body carries the shop, locale negotiation, and session context under `metadata` — here `metadata.fluid_shop` is the full host (e.g. `acme.fluid.app`), un…
- [An array of available checkout and order confirmation drop zones (public)](https://docs.fluid.app/api-reference/public-drop-zones/an-array-of-available-checkout-and-order-confirmation-drop-zones-public.md): Returns active checkout and order-confirmation drop zones for the requested Fluid shop. This is an SDK-internal surface used by the FairShare SDK; direct REST integrations should use checkout-v2026-04.
- [Auth auth](https://docs.fluid.app/api-reference/public/auth-auth.md)
- [Countries countries](https://docs.fluid.app/api-reference/public/countries-countries.md)
- [Db Port db port](https://docs.fluid.app/api-reference/public/db-port-db-port.md)
- [Get apple pay domain](https://docs.fluid.app/api-reference/public/get-apple-pay-domain.md)
- [Health health](https://docs.fluid.app/api-reference/public/health-health.md)
- [Homepage Render homepage render](https://docs.fluid.app/api-reference/public/homepage-render-homepage-render.md)
- [Realtime realtime](https://docs.fluid.app/api-reference/public/realtime-realtime.md)
- [Update Volumes update volumes](https://docs.fluid.app/api-reference/public/update-volumes-update-volumes.md): Overrides a line item's CV and QV volumes. Used by admin tooling; requires a bearer token.
- [Get root theme by ID](https://docs.fluid.app/api-reference/root-themes/get-root-theme-by-id.md)
- [List root themes](https://docs.fluid.app/api-reference/root-themes/list-root-themes.md)
- [Start a new session](https://docs.fluid.app/api-reference/session/start-a-new-session.md)
- [Retrieve page settings](https://docs.fluid.app/api-reference/settings/retrieve-page-settings.md)
- [Confirm MFA via SSO](https://docs.fluid.app/api-reference/single-sign-ons/confirm-mfa-via-sso.md): Verify a multi-factor authentication code through the SSO flow.
- [Get company via SSO](https://docs.fluid.app/api-reference/single-sign-ons/get-company-via-sso.md): Public endpoint that returns company details for SSO login pages.
- [Get current user via SSO](https://docs.fluid.app/api-reference/single-sign-ons/get-current-user-via-sso.md): Decode a JWT and return user and user-company profile information through the SSO flow.
- [Resend MFA via SSO](https://docs.fluid.app/api-reference/single-sign-ons/resend-mfa-via-sso.md): Resend a verification code through the SSO flow.
- [Send MFA via SSO](https://docs.fluid.app/api-reference/single-sign-ons/send-mfa-via-sso.md): Send a multi-factor authentication passcode via the SSO flow.
- [Link Apple account](https://docs.fluid.app/api-reference/social-auth/link-apple-account.md): Link an Apple account to the authenticated user.
- [List social auth providers](https://docs.fluid.app/api-reference/social-auth/list-social-auth-providers.md): Return available social auth providers with their OAuth URLs for a given shop.
- [Redirect to Apple OAuth](https://docs.fluid.app/api-reference/social-auth/redirect-to-apple-oauth.md): Generate an Apple OAuth URL for redirect-based authentication.
- [Redirect to Facebook OAuth](https://docs.fluid.app/api-reference/social-auth/redirect-to-facebook-oauth.md): Generate a Facebook OAuth URL for redirect-based authentication.
- [Redirect to Google OAuth](https://docs.fluid.app/api-reference/social-auth/redirect-to-google-oauth.md): Generate a Google OAuth URL for redirect-based authentication.
- [Social auth callback](https://docs.fluid.app/api-reference/social-auth/social-auth-callback.md): Handle the OAuth callback from a social auth provider. Finds or creates the user and initiates MFA.
- [Apple Pay domain verification](https://docs.fluid.app/api-reference/store/apple-pay-domain-verification.md): Public endpoint — returns the Apple Pay domain verification file for the given hostname.
- [Get address fields for country](https://docs.fluid.app/api-reference/store/get-address-fields-for-country.md): Public endpoint — returns the address form schema for a given country.
- [Get agreement content](https://docs.fluid.app/api-reference/store/get-agreement-content.md): Public endpoint — returns agreement content by ID.
- [Get checkout config](https://docs.fluid.app/api-reference/store/get-checkout-config.md): Returns checkout configuration for the authenticated company. Requires JWT.
- [List available countries](https://docs.fluid.app/api-reference/store/list-available-countries.md): Returns checkout countries for an authenticated customer, or for a guest checkout when cart_token is supplied.
- [List available languages](https://docs.fluid.app/api-reference/store/list-available-languages.md): Lists the languages the store supports for localized content. Requires a company bearer token; returns `401` when unauthenticated.
- [List drop zones](https://docs.fluid.app/api-reference/store/list-drop-zones.md): Public endpoint — returns CMS drop zones for the checkout. Requires fluid_shop query param.
- [List playlists (public storefront catalog)](https://docs.fluid.app/api-reference/storefront/list-playlists-public-storefront-catalog.md): PUBLIC endpoint — NO authentication required. Company is resolved from the request subdomain. Returns only live playlists: `active == true` (inactive/ draft playlists are excluded). Cursor-paginated. Supports `lang`, `q`, `filter[country]`, `filter[language]`, and `sort`.
- [Products in a Category (public)](https://docs.fluid.app/api-reference/storefront/products-in-a-category-public.md): PUBLIC endpoint — NO authentication required. Company is resolved from the request subdomain.
- [Products in a Collection (public)](https://docs.fluid.app/api-reference/storefront/products-in-a-collection-public.md): PUBLIC endpoint — NO authentication required. Company is resolved from the request subdomain.
- [Public Categories catalog](https://docs.fluid.app/api-reference/storefront/public-categories-catalog.md): Unauthenticated. Company is resolved from the request subdomain. Returns ONLY live categories (active + resolved-published, country-eligible, language-eligible) — non-public rows never leak.
- [Public Category by slug](https://docs.fluid.app/api-reference/storefront/public-category-by-slug.md): Unauthenticated. Resolves by slug (the canonical public identifier; matches `canonical_url`). Returns 404 for any non-live row so unlisted categories never leak their existence.
- [Public Collection by slug](https://docs.fluid.app/api-reference/storefront/public-collection-by-slug.md): Unauthenticated. Resolves by slug (the canonical public identifier; matches `canonical_url`). Returns 404 ONLY for an `archived` row — draft / scheduled / inactive collections resolve here (so preview + pre-launch links load) and render noindex at the theme layer.
- [Public Collections catalog](https://docs.fluid.app/api-reference/storefront/public-collections-catalog.md): Unauthenticated. Company is resolved from the request subdomain. Returns ONLY live collections (active + resolved-published, country-eligible, language-eligible) — non-public rows never leak.
- [Public Enrollment Pack by slug](https://docs.fluid.app/api-reference/storefront/public-enrollment-pack-by-slug.md): Unauthenticated. Resolves by slug (the canonical public identifier; matches `canonical_url`). Show is more permissive than the catalog: an inactive (draft) pack still resolves by direct slug (rendered noindex); only discarded packs return 404, never 403. Includes the full pack contents (membership +…
- [Public Enrollment Packs catalog](https://docs.fluid.app/api-reference/storefront/public-enrollment-packs-catalog.md): Unauthenticated. Company is resolved from the request subdomain. Returns ONLY live packs (active + non-discarded), country- and language-eligible — non-public rows never leak. The heavy pack contents are on the show response, not the catalog card.
- [Public Media catalog](https://docs.fluid.app/api-reference/storefront/public-media-catalog.md): Unauthenticated. Company is resolved from the request subdomain. Returns ONLY live media (active + resolved-published + non-discarded), country- and language-eligible — non-public rows never leak. A future-scheduled medium appears automatically once its `publish_at` passes.
- [Public Medium by slug](https://docs.fluid.app/api-reference/storefront/public-medium-by-slug.md): Unauthenticated. Resolves by slug (the canonical public identifier; matches `canonical_url`). Show is more permissive than the catalog: a draft (inactive) or future-scheduled medium still resolves by direct slug (rendered noindex); only discarded media return 404, never 403.
- [Public Page by slug](https://docs.fluid.app/api-reference/storefront/public-page-by-slug.md): Unauthenticated. Resolves by slug (the canonical public identifier; matches `canonical_url`). Show is more permissive than the catalog: a draft or future-scheduled page still resolves by direct slug (rendered noindex on the HTML surface); only discarded pages return 404, never 403. The same payload…
- [Public Pages catalog](https://docs.fluid.app/api-reference/storefront/public-pages-catalog.md): Unauthenticated. Company is resolved from the request subdomain. Returns ONLY live pages (publish toggle on + resolved-published + non-discarded), country- and language-eligible — non-public rows never leak. A future-scheduled page appears automatically once its `publish_at` passes. Pages are a META…
- [Public Post by slug](https://docs.fluid.app/api-reference/storefront/public-post-by-slug.md): Unauthenticated. Resolves by slug. Returns 404 for archived or discarded posts; draft / scheduled / inactive posts resolve (noindex at the theme layer).
- [Public Posts (blog) catalog](https://docs.fluid.app/api-reference/storefront/public-posts-blog-catalog.md): Unauthenticated. Company is resolved from the request subdomain. Returns ONLY live posts (active + resolved-published, country-eligible, language-eligible, not discarded).
- [Public Product by slug](https://docs.fluid.app/api-reference/storefront/public-product-by-slug.md): PUBLIC endpoint — NO authentication required. Resolves by slug (the canonical public identifier; matches `canonical_url`). Show is more permissive than the catalog: draft, scheduled (future `publish_at`), and inactive products still resolve by direct slug — so preview and pre-launch links load — but…
- [Public Products catalog](https://docs.fluid.app/api-reference/storefront/public-products-catalog.md): PUBLIC endpoint — NO authentication required. Company is resolved from the request subdomain. Returns ONLY live products (active + resolved-published) that have an active variant in the requested `country`. Non-live rows never leak.
- [Show a playlist (public, by slug)](https://docs.fluid.app/api-reference/storefront/show-a-playlist-public-by-slug.md): PUBLIC endpoint — NO authentication required. Returns any non-discarded playlist by slug: `draft`, `inactive`, and live playlists all resolve (so preview / pre-launch links work). Only discarded playlists return 404. Non-live playlists render with `noindex` metadata. The response uses the `:detail`…
- [Create subscription bundle](https://docs.fluid.app/api-reference/subscription-bundles/create-subscription-bundle.md): Creates a subscription bundle from the supplied `bundle` definition. Requires a bearer token. Returns `422` on validation failure and `401` when unauthenticated.
- [List subscription bundles](https://docs.fluid.app/api-reference/subscription-bundles/list-subscription-bundles.md): Lists the subscription bundles available to the authenticated customer. Requires a bearer token. Returns `422` on invalid query parameters and `401` when unauthenticated.
- [Attach subscription discount](https://docs.fluid.app/api-reference/subscriptions/attach-subscription-discount.md): Attaches a discount to the subscription `{token}`, by `discount_id` or `discount_code`, optionally scoped by `duration`/`duration_cycles`. Requires a bearer token. Returns `422` on validation failure, `403` when not permitted, `404` when the subscription is not found, and `401` when unauthenticated.
- [Cancel subscription](https://docs.fluid.app/api-reference/subscriptions/cancel-subscription.md): Cancels the subscription `{token}`; no further billing cycles run. Requires a bearer token. Returns `422` when it cannot be cancelled in its current state, `404` when not found, and `401` when unauthenticated.
- [Create a subscription](https://docs.fluid.app/api-reference/subscriptions/create-a-subscription.md): Creates a subscription from the supplied `subscription` payload. Requires a bearer token. Returns `201` on success, `422` on validation failure, `404` when a referenced resource is not found, and `401` when unauthenticated.
- [List subscription discounts](https://docs.fluid.app/api-reference/subscriptions/list-subscription-discounts.md): Lists the discounts attached to the subscription `{token}`. Requires a bearer token. Returns `403` when the caller may not view the subscription, `404` when it is not found, and `401` when unauthenticated.
- [List subscriptions](https://docs.fluid.app/api-reference/subscriptions/list-subscriptions.md): Lists the authenticated customer's subscriptions. IDOR-safe: scoped to current_customer.
- [Pause subscription](https://docs.fluid.app/api-reference/subscriptions/pause-subscription.md): Pauses billing on the subscription `{token}` until it is resumed. Requires a bearer token. Returns `422` when it cannot be paused in its current state, `404` when not found, and `401` when unauthenticated.
- [Preview a failed-cycle waiver](https://docs.fluid.app/api-reference/subscriptions/preview-a-failed-cycle-waiver.md): Returns the authoritative future billing and shipping timestamps that would be restored if the exhausted failed cycle were waived. An ineligible subscription returns 200 with eligible false and null dates.
- [Reactivate subscription](https://docs.fluid.app/api-reference/subscriptions/reactivate-subscription.md): Reactivates a cancelled or expired subscription `{token}`, optionally setting `next_bill_date`, `process_immediately`, or a billing `address_id`. Requires a bearer token. Returns `422` when it cannot be reactivated, `404` when not found, and `401` when unauthenticated.
- [Remove subscription discount](https://docs.fluid.app/api-reference/subscriptions/remove-subscription-discount.md): Detaches the discount `{id}` from the subscription `{token}`. Requires a bearer token. Returns `422` when it cannot be removed, `403` when not permitted, `404` when the subscription or discount is not found, and `401` when unauthenticated.
- [Resume subscription](https://docs.fluid.app/api-reference/subscriptions/resume-subscription.md): Resumes a paused subscription `{token}`, restarting its billing schedule. Requires a bearer token. Returns `422` when it cannot be resumed in its current state, `404` when not found, and `401` when unauthenticated.
- [Retry billing on a past-due subscription](https://docs.fluid.app/api-reference/subscriptions/retry-billing-on-a-past-due-subscription.md): Queues an immediate billing attempt against the payment method currently on file. The endpoint is idempotent for a found subscription. A rapid duplicate returns queued true while preserving the first retry time and does not enqueue another billing attempt.
- [Show subscription](https://docs.fluid.app/api-reference/subscriptions/show-subscription.md): Returns the subscription identified by `{token}`, including its plan, items, and schedule. Requires a bearer token. Returns `404` when the token does not resolve and `401` when unauthenticated.
- [Skip subscription](https://docs.fluid.app/api-reference/subscriptions/skip-subscription.md): Skips the subscription's next scheduled cycle for `{token}`. Requires a bearer token. Returns `422` when the next cycle cannot be skipped, `404` when not found, and `401` when unauthenticated.
- [Skip the exhausted failed cycle](https://docs.fluid.app/api-reference/subscriptions/skip-the-exhausted-failed-cycle.md): Waives the missed billing and shipping cycle without collecting payment and without creating an order or shipment. The missed shipment is skipped. The subscription's original billing and shipping cadence and anchors are preserved, and each stored next date is advanced independently only as needed to…
- [Undo_skip subscription](https://docs.fluid.app/api-reference/subscriptions/undo_skip-subscription.md): Reverses a previously skipped cycle on the subscription `{token}`, restoring its next scheduled cycle. Requires a bearer token. Returns `422` when there is no skip to undo, `404` when not found, and `401` when unauthenticated.
- [Update subscription](https://docs.fluid.app/api-reference/subscriptions/update-subscription.md): Updates the subscription `{token}` from the supplied `subscription` payload (PATCH semantics — only supplied keys change). Requires a bearer token. Returns `422` on validation failure, `404` when not found, and `401` when unauthenticated.
- [Switch user role](https://docs.fluid.app/api-reference/switch-role/switch-user-role.md): Switch the current admin user to act as a different role (admin or rep).
- [Exchange JWT for user company token](https://docs.fluid.app/api-reference/token-exchange/exchange-jwt-for-user-company-token.md): Exchange a JWT for a long-lived user-company token (the inverse of `token_exchange`). The JWT is supplied in the request body, so no bearer header is required. Returns `401` when the JWT is invalid or has been rejected by a lock/flush.
- [Exchange user company token for customer JWT](https://docs.fluid.app/api-reference/token-exchange/exchange-user-company-token-for-customer-jwt.md): Exchange a user-company token for a customer-scoped JWT, creating a customer record if one does not yet exist. The token is supplied in the request body, so no bearer header is required. Returns `401` when the user-company token is blank or does not match a user company, and `400` when the customer…
- [Exchange user company token for JWT](https://docs.fluid.app/api-reference/token-exchange/exchange-user-company-token-for-jwt.md): Exchange a user-company token for a bearer JWT (the inverse of `jwt_exchange`). The token is supplied in the request body, so no bearer header is required. Returns `401` when the user-company token is blank or does not match a user company.
- [Refresh JWT token](https://docs.fluid.app/api-reference/token-exchange/refresh-jwt-token.md): Refresh an existing JWT and return a new one with extended validity. The current JWT is supplied in the request body, so no bearer header is required. Returns `401` when that JWT is invalid or has been rejected by a lock/flush.
- [Capture an authorization](https://docs.fluid.app/api-reference/transactions/capture-an-authorization.md): Captures funds previously held by an authorization. Send `amount_cents` for a partial capture; omit it to capture the full authorized amount. Creates a `capture` transaction linked to the authorization via `parent_transaction_id` and returns it with `201`. Pass an `Idempotency-Key` header to make re…
- [Credit/refund a transaction](https://docs.fluid.app/api-reference/transactions/creditrefund-a-transaction.md): Refunds or credits a prior transaction. Send `amount_cents` for a partial refund; omit it to refund the full amount. Partial refunds accumulate in the source transaction's `credited_amount_cents`. Creates a `refund`/ `general_credit` transaction linked via `parent_transaction_id` and returns it with…
- [Get a transaction](https://docs.fluid.app/api-reference/transactions/get-a-transaction.md): Retrieves a single transaction by slug, including its action, status, amounts, and fee breakdown. Read-only. Returns `404` when no transaction matches the slug for the authenticated merchant.
- [List transactions](https://docs.fluid.app/api-reference/transactions/list-transactions.md): Lists transactions for the authenticated merchant using `limit`/`offset` pagination. Read-only. Requires a valid API key or JWT bearer token (`401` if missing/invalid, `403` if the credential is not authorized).
- [Void an authorization](https://docs.fluid.app/api-reference/transactions/void-an-authorization.md): Voids (cancels) an authorization before it is captured, releasing the held funds. Creates a `void` transaction linked via `parent_transaction_id` and returns it with `200`. Pass an `Idempotency-Key` header to make retries safe. Returns `404` when the authorization is not found, `409` on an in-flight…
- [List webhook schemas](https://docs.fluid.app/api-reference/webhook-schemas/list-webhook-schemas.md): Lists the published JSON payload schemas for webhook events — use them to generate types or validate deliveries. Read-only. The optional `event_identifier` query parameter narrows the list to a single event's schema. Requires a company Bearer token (`401` otherwise).
- [Show a webhook schema](https://docs.fluid.app/api-reference/webhook-schemas/show-a-webhook-schema.md): Returns the latest schema for a specific event identifier.
- [List webhook resources](https://docs.fluid.app/api-reference/webhooks-resources/list-webhook-resources.md): Lists the resources you can subscribe to and the events available on each — call it before creating a subscription to discover valid `resource`/`event` pairs. Read-only. The response also carries `deprecated_resources`: topics slated for removal (migrate to the `member_*` topics). Requires a company…
- [Bulk delete webhooks](https://docs.fluid.app/api-reference/webhooks/bulk-delete-webhooks.md): Deletes several webhook subscriptions in one call. Requires a `webhook_ids` array of integer ids. Returns `200` with the deleted `webhook_ids` and their `count`. Requires a company Bearer token (`401` otherwise).
- [Create a webhook](https://docs.fluid.app/api-reference/webhooks/create-a-webhook.md): Creates a webhook subscription: Fluid delivers a JSON payload to `url` each time the chosen `event` fires on the chosen `resource`. `resource`, `event`, and `url` are required; `active`, `http_method`, and `auth_token` (the shared secret Fluid signs deliveries with) are optional. Returns `201` with…
- [Delete a webhook](https://docs.fluid.app/api-reference/webhooks/delete-a-webhook.md): Deletes a webhook subscription by its numeric `id`; Fluid stops delivering its events. Returns `200` echoing the deleted webhook's `id`, or `404` when the id is unknown. Requires a company Bearer token (`401` otherwise).
- [Get webhook events for a resource](https://docs.fluid.app/api-reference/webhooks/get-webhook-events-for-a-resource.md): Returns the most recent delivered event for `resource_name` as the same envelope Fluid POSTs to your endpoint (the event `id`, `identifier`, `name`, `timestamp`, and the enriched `payload`) — use it to confirm what Fluid last sent. Read-only. Pass a resource the company has actually registered; an u…
- [List webhooks](https://docs.fluid.app/api-reference/webhooks/list-webhooks.md): Lists the company's webhook subscriptions, paginated. Read-only. The optional `query` object narrows results by `active`, `resource`, or free-text `search_query`, and pages with `page`/`per_page` (max 100). Requires a company Bearer token (`401` otherwise).
- [Show a webhook](https://docs.fluid.app/api-reference/webhooks/show-a-webhook.md): Fetches a single webhook subscription by its numeric `id`. Read-only. Returns `404` when no webhook with that id belongs to the company. Requires a company Bearer token (`401` otherwise).
- [Update a webhook](https://docs.fluid.app/api-reference/webhooks/update-a-webhook.md): Updates a webhook subscription. The body accepts `url`, `active`, `auth_token`, and `http_method`; `resource` and `event` are fixed at creation — retarget by deleting and recreating. Rotate the signing secret by sending a new `auth_token`. Returns `200` with the updated subscription, `404` when the…
- [Retrieve banner widget](https://docs.fluid.app/api-reference/widgets/retrieve-banner-widget.md)
- [Retrieve cart widget](https://docs.fluid.app/api-reference/widgets/retrieve-cart-widget.md)
- [Retrieve chat widget](https://docs.fluid.app/api-reference/widgets/retrieve-chat-widget.md)
- [Retrieve popup widget](https://docs.fluid.app/api-reference/widgets/retrieve-popup-widget.md)
- [Fluid API Authentication — Token Types and Scopes](https://docs.fluid.app/api/authentication.md): Learn how to authenticate Fluid API requests using company, partner, and public tokens, how to pass a bearer token, and the storefront company scopes.
- [Choosing a cart surface: Checkout API vs. Public SDK API](https://docs.fluid.app/api/choosing-a-cart-surface.md): Choose between Fluid's direct Checkout API and the Public SDK API used by the FairShare SDK.
- [Work with the category hierarchy](https://docs.fluid.app/api/guides/category-hierarchy.md): Create child categories, list top-level categories, and traverse parents and children using parent_id and has_children.
- [Control country availability](https://docs.fluid.app/api/guides/country-availability.md): Set which countries a category or collection is available in, read a row's country list, and filter the catalog by country.
- [Embed apps with drop zones](https://docs.fluid.app/api/guides/drop-zones.md): Choose the right Drop Zones surface and embed external apps safely in Fluid.
- [Find and create categories and collections](https://docs.fluid.app/api/guides/find-and-create-categories-and-collections.md): Browse the public catalog, look up categories and collections by slug or id, and create new ones with the company API.
- [Manage global embeds](https://docs.fluid.app/api/guides/global-embeds.md): Add and review privileged HTML or scripts for storefront and checkout pages.
- [Build a headless checkout](https://docs.fluid.app/api/guides/headless-commerce.md): Drive a custom purchase flow on Fluid's checkout surface — create a cart, add line items, capture the buyer's contact and address, select shipping, collect payment, and complete the order.
- [Rename, publish, and schedule](https://docs.fluid.app/api/guides/rename-publish-and-schedule.md): Rename a category or collection, control whether it is publicly visible, and schedule it to go live at a future time.
- [Translate a resource](https://docs.fluid.app/api/guides/translate-resources.md): Write translations onto storefront resources with the lang query parameter, read a locale back, and understand why a translation write is always a company PATCH.
- [Register and handle webhooks](https://docs.fluid.app/api/guides/webhooks.md): Subscribe to Fluid events over HTTPS, verify deliveries with a shared secret, handle the delivery envelope, and inspect the most recent delivered event for a resource.
- [Fluid Commerce API Reference — Overview and Base URLs](https://docs.fluid.app/api/overview.md): The Fluid Commerce API is a versioned REST API. This overview covers base URLs, the v2026-04 surface, the standard response envelope, error shapes, and cursor pagination.
- [Public forms API](https://docs.fluid.app/api/public/forms.md): Move from the sunset unauthenticated form endpoint to the token-based forms operations used by the Public SDK API.
- [We-Commerce Checkout: High-Converting One-Page Checkout](https://docs.fluid.app/concepts/checkout.md): Fluid Checkout at checkout.fluid.app handles payments, shipping, tax, and rep attribution on one page, with saved profiles to boost conversions.
- [Droplets: Extend Fluid with Third-Party Integrations](https://docs.fluid.app/concepts/droplets.md): Droplets are modular third-party integrations for the Fluid platform. Install pre-built apps from the Marketplace or build your own custom Droplet.
- [FairShare: Sales Rep Attribution Across Multiple Domains](https://docs.fluid.app/concepts/fair-share.md): FairShare accurately attributes sales credit to reps using cookies, fingerprints, and URL routes across multiple websites and domains.
- [What is We-Commerce? Direct Sales Meets E-Commerce](https://docs.fluid.app/concepts/we-commerce.md): We-Commerce is Fluid's approach to combining direct sales and e-commerce so merchants and reps can collaborate with full transparency on every sale.
- [Build a Shopping Cart with Fluid: Cart API and SDK Guide](https://docs.fluid.app/guides/build-shopping-cart.md): Learn how to build a shopping cart using Fluid's cart API and FairShare SDK — including products, cart creation, real-time updates, and checkout.
- [Build and Publish a Fluid Droplet: Setup to Marketplace](https://docs.fluid.app/guides/creating-droplets.md): Learn how to create, configure, and publish a Fluid Droplet — including the installation webhook flow, credential exchange, and Marketplace submission.
- [Embed Fluid's DAM Picker: Asset Selection SDK Guide](https://docs.fluid.app/guides/dam-picker.md): Learn how to embed Fluid's Digital Asset Management file picker with the @fluid-app/dam-picker SDK — including React bindings, framework integrations, multi-select, and upload handling.
- [Fluid: The We-Commerce Platform for Direct Sales Teams](https://docs.fluid.app/introduction.md): Fluid is a We-Commerce platform combining e-commerce and direct sales tools. Learn how Fluid helps merchants and reps sell together with full transparency.
- [Migrate to server-side attribution](https://docs.fluid.app/migration/server-side-attribution.md): Remove retired FairShare attribution-pattern attributes and use automatic attribution or an explicit rep override.
- [Fluid Platform: Components, Features, and How They Connect](https://docs.fluid.app/platform-overview.md): Explore the core components of the Fluid We-Commerce platform: FairShare attribution, Payments, Checkout, Website Editor, and Droplets.
- [Fluid Quickstart: Account, FairShare SDK, and First API Call](https://docs.fluid.app/quickstart.md): Create your Fluid account, add the FairShare SDK to your website, and confirm your integration with a live API call — all in under 10 minutes.
- [FairShare Cart API: JavaScript Methods and HTML Controls](https://docs.fluid.app/sdk/cart-api.md): Full reference for the FairShare cart JavaScript API — add items, update quantities, subscribe, checkout, and control the cart widget programmatically.
- [FairShare Web Components](https://docs.fluid.app/sdk/components.md): Use FairShare cart, banner, lead capture, and media web components.
- [Files SDK](https://docs.fluid.app/sdk/files-sdk.md): Embed Fluid's DAM picker to browse, upload, transform, and select assets from your application.
- [Install the FairShare SDK on Any Website in Minutes](https://docs.fluid.app/sdk/installation.md): Add the FairShare SDK to any website with a single script tag. Configure your shop ID, attribution settings, and optional real-time updates.
- [FairShare media](https://docs.fluid.app/sdk/media.md): Embed FairShare media, listen for playback events, and configure calls to action.
- [FairShare SDK: Attribution and Commerce for Any Website](https://docs.fluid.app/sdk/overview.md): FairShare SDK adds sales rep attribution, cart management, lead capture, and media widgets to any website using a single script tag.
- [Hydrate affiliate details in a cached theme](https://docs.fluid.app/themes/affiliate-hydration.md): Render affiliate names, images, links, and conditional content safely in cacheable Fluid themes.
- [Choose blocks or components](https://docs.fluid.app/themes/blocks-and-components.md): Choose between components, inline blocks, and standalone theme blocks when you build reusable Fluid theme UI.
- [Configure cart feedback](https://docs.fluid.app/themes/cart-feedback.md): Configure loading spinners and optional cart toasts in a Fluid theme.
- [Fluid CLI: Local Theme Development and Deployment Tool](https://docs.fluid.app/themes/cli.md): Use the Fluid CLI to develop, pull, and push themes locally — with commands for authentication, company switching, and live development servers.
- [Developer Guide: Building and Customizing Fluid Themes](https://docs.fluid.app/themes/developer-guide.md): Learn how to build and customize Fluid themes using Liquid templating, JSON section schemas, components, assets, and locale files for translations.
- [Connect a theme to GitHub](https://docs.fluid.app/themes/github-integration.md): Import a Fluid theme from a GitHub branch and keep theme changes in your repository workflow.
- [Transform theme images](https://docs.fluid.app/themes/image-transformations.md): Resize, crop, and reformat ImageKit images with the image_url and img_url Liquid filters.
- [Link editor presets to CSS variables](https://docs.fluid.app/themes/linked-css-variable-presets.md): Connect page-editor typography, color, radius, and spacing presets to theme CSS variables.
- [Render responsive media](https://docs.fluid.app/themes/media-tag.md): Render responsive images and videos with the media_tag Liquid filter.
- [Fluid Themes: Overview, Architecture, and Hierarchy](https://docs.fluid.app/themes/overview.md): Fluid's themes system lets you build fully custom websites using Liquid templating, JSON section schemas, and a drag-and-drop visual editor.
- [Fluid Page Editor: Visual Page Building and Editing](https://docs.fluid.app/themes/page-editor.md): The Fluid Page Editor lets you customize pages visually — click to select sections, edit settings in the panel, and see changes in real time.
- [Build a product bundle selector](https://docs.fluid.app/themes/product-bundles.md): Render bundle groups, collect shopper selections, and add the configured bundle to a cart.
- [Configure a root theme](https://docs.fluid.app/themes/root-theme-configuration.md): Connect theme settings, stored values, CSS variables, and section styles across Fluid's Base, Vox, and Fluid root themes.
- [Build theme schemas](https://docs.fluid.app/themes/schema-components.md): Define section settings, blocks, presets, resource selectors, and reusable option groups for Fluid's visual editor.
- [Supported storefront paths](https://docs.fluid.app/themes/supported-paths.md): Choose the correct Fluid storefront route for each theme template and affiliate context.
- [Use Liquid theme variables](https://docs.fluid.app/themes/theme-variables.md): Reference the global and template-scoped Liquid data available while Fluid renders a storefront theme.

## OpenAPI Specs

- [payment-v2026-04](https://docs.fluid.app/api-reference/payment-v2026-04.yaml)
- [public-v2025-06](https://docs.fluid.app/api-reference/public-v2025-06.yaml)
- [checkout-v2026-04](https://docs.fluid.app/api-reference/checkout-v2026-04.yaml)
- [auth-v0](https://docs.fluid.app/api-reference/auth-v0.yaml)
- [payments-v2026-04](https://docs.fluid.app/api-reference/payments-v2026-04.yaml)
- [storefront-v2026-04](https://docs.fluid.app/api-reference/storefront-v2026-04.yaml)
- [webhooks-v0](https://docs.fluid.app/api-reference/webhooks-v0.yaml)
- [commerce-v2026-04](https://docs.fluid.app/api-reference/commerce-v2026-04.yaml)