> ## Documentation Index > Fetch the complete documentation index at: https://docs.fluid.app/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > For new direct REST integrations, use the v2026-04 surfaces. The @fluid-app FairShare SDK continues to use its own published public-v2025-06 contract. > Authenticate with the header Authorization: Bearer ; public storefront read endpoints require no auth. > Lists use cursor pagination via the page[cursor] and page[limit] query params; follow meta.pagination.next_cursor until it is null. > Never use /api/company/v1 or /api/v1 paths, page/per_page params, or offset pagination — they are legacy. > The OpenAPI specs under api-reference/ are the authoritative contracts; prefer them over prose when in doubt. api-reference/storefront-v2026-04.yaml covers the v2026-04 storefront surface (/api/v202604/... paths); api-reference/auth-v0.yaml covers the unversioned auth surface (/api/... paths — authentication, MFA, social auth, and token exchange); api-reference/checkout-v2026-04.yaml covers the v2026-04 checkout surface (/api/checkout/v2026-04/... paths — carts, cart auth, discounts, items, subscriptions, orders, enrollments, and store config); api-reference/public-v2025-06.yaml covers the Public SDK surface used by the @fluid-app FairShare SDK, including its parallel cart lifecycle, browser integrations, versioned payment callbacks, unversioned public utilities, and the cart price-override operation; api-reference/payment-v2026-04.yaml covers the v2026-04 payment gateway admin surface (/api/payment/v2026-04/... paths, bearer-authenticated — gateway CRUD, gateway purchase/authorize/$0-verify, transaction list/show and capture/void/credit, and merchant payment configuration); api-reference/payments-v2026-04.yaml covers the v2026-04 cart payment surface (/api/payments/v2026-04/carts/{cart_token}/... paths, authenticated by the cart token in the path with no bearer — payment-method selection, VGS card tokenization, 3D Secure verification, and PayPal/Braintree/Klarna/Apple Pay flows); api-reference/commerce-v2026-04.yaml covers the v2026-04 commerce order-editing surface (/api/v202604/orders/{order_id}/edits paths, bearer-authenticated — post-checkout order edits that atomically insert items and add adjustments/discounts, with an optional dry-run preview); api-reference/webhooks-v0.yaml covers the unversioned webhooks surface (/api/... paths — webhook registration, delivery payloads, callback registrations, company events, and webhook/callback schemas). > Successful responses wrap the resource payload alongside a top-level integer status and a meta object. # Choosing a cart surface: Checkout API vs. Public SDK API > Choose between Fluid's direct Checkout API and the Public SDK API used by the FairShare SDK. Fluid publishes two REST surfaces for carts: * The **Checkout API** is for direct REST integrations. * The **Public SDK API** is the contract behind the `@fluid-app` FairShare SDK. They are two versioned front doors to the same cart engine. A cart token created through either surface identifies the same cart on the other. The surfaces are not aliases, however. Their operation names and request shapes differ, and one bundle-subscription behavior differs materially. Use one surface for each cart lifecycle. Follow the generated reference links below for the current request and response contracts. ## Choose a surface | If you are | Use | Why | | ------------------------------------------------------ | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Building a new direct REST integration | **Checkout API** | It is the forward surface for direct integrations. It also owns customer accounts, subscription management, store configuration, cart points, and directory lookups. | | Using the `@fluid-app` FairShare SDK | **Public SDK API** | This is the only REST contract the SDK registers. Its cart methods call this surface for you. | | Building storefront widgets, tracking, media, or forms | **Public SDK API** | These browser-facing capabilities do not exist on the Checkout API. | | Building enrollment-pack carts | **Public SDK API** | Enrollment-pack lookup and cart enrollment are unique to this surface. | | Handling payment-gateway callbacks | **Public SDK API** or **Cart payment API** | The Checkout API does not own gateway callbacks. | ## Distinguish the two `v2025-06` APIs Two unrelated APIs carry the same version label: | Label | Surface | | ------------------------ | --------------------------------------------------------------------------------------- | | `/api/public/v2025-06/…` | The browser-facing **Public SDK API** described here. | | `/api/v2025-06/…` | A separate admin and partner API. Its resources and authentication model are unrelated. | The Public SDK API version names the specification, not one uniform path prefix. Most operations use `/api/public/v2025-06/`. The same spec also owns payment callbacks under `/api/v202506/carts/`, several unversioned public utilities, and a cart price-override operation under `/api/carts/`. Use each generated operation page as the source of truth for its exact path. ## Map equivalent operations The table contains the 21 shared integration operations. Several operations that the Checkout API combines are separate operations on the Public SDK API. | Operation | Checkout API | Public SDK API | | ------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | Create a cart | [Create a cart](/api-reference/carts/create-a-cart) | [Creates a cart](/api-reference/carts/creates-a-cart) | | Read a cart | [Show a cart](/api-reference/carts/show-a-cart) | [Retrieves a cart](/api-reference/carts/retrieves-a-cart) | | Update buyer contact details | [Update cart attributes](/api-reference/carts/update-cart-attributes) | [Updates a cart](/api-reference/carts/updates-a-cart) | | Add or change item quantities | [Add items to cart](/api-reference/cart-items/add-items-to-cart) | [Adds items to cart](/api-reference/carts/adds-items-to-cart) | | Change a line's variant | [`PATCH items/{id}`](/api-reference/cart-items/update-a-cart-item) | [`PATCH items/{item_id}/variant`](/api-reference/carts/updates-a-cart-items-variant) | | Subscribe or unsubscribe a line | [`PATCH items/{id}`](/api-reference/cart-items/update-a-cart-item) | [`POST` subscribe](/api-reference/carts/subscribes-a-cart-item) or [`DELETE` subscribe](/api-reference/carts/updates-subscribe:false-to-cart-item) | | Remove a line | [Remove a cart item](/api-reference/cart-items/remove-a-cart-item) | [Removes item from cart](/api-reference/carts/removes-item-from-cart) | | Set an address | [Set cart address](/api-reference/carts/set-cart-address) | [Updates cart address](/api-reference/carts/updates-cart-address) | | Select shipping | [`PUT shipping`](/api-reference/carts/select-shipping-method) | [`POST shipping_method`](/api-reference/carts/sets-cart-shipping-method) | | Apply a discount code | [Apply discount code](/api-reference/cart-discount/apply-discount-code) | [Applies a discount to the cart](/api-reference/carts/applies-a-discount-to-the-cart) | | Change country | [`country`](/api-reference/carts/change-cart-country) | [`update_country`](/api-reference/carts/updates-the-country-of-a-cart-also-updates-the-currency-code) | | Change language | [`language`](/api-reference/carts/update-cart-language) | [`change_language`](/api-reference/carts/updates-the-language-of-a-cart) | | Complete the cart | [`complete`](/api-reference/carts/complete-checkout) | [`checkout`](/api-reference/carts/completes-cart-checkout) | | Send a sign-in link | [`auth/magic_link`](/api-reference/cart-auth/send-magic-link) | [`magic_link`](/api-reference/carts/create-magic-link-for-cart) | | Confirm a sign-in link | [`auth/verify`](/api-reference/cart-auth/verify-magic-link) | [`confirm_magic_link`](/api-reference/carts/confirm-magic-link-for-cart) | | Sign the buyer out | [Logout from cart](/api-reference/cart-auth/logout-from-cart) | [Removes rep buyer and customer](/api-reference/carts/removes-rep_buyer-and-customer-for-the-cart) | | Attach a signed-in customer | [Sync customer data to cart](/api-reference/carts/sync-customer-data-to-cart) | [Syncs cart with authenticated customer](/api-reference/carts/syncs-cart-with-authenticated-customer) | | Read a completed order | [Show order](/api-reference/orders/show-order) | [Retrieves an order with points redemption](/api-reference/orders/retrieves-an-order-with-points-redemption) | | Query a product for the cart | [Query product](/api-reference/products/query-product) | [Get product by slug](/api-reference/product/get-product-by-slug-in-a-foreign-local-includes-the-correct-variants) | | Verify an Apple Pay domain | [Apple Pay domain verification](/api-reference/store/apple-pay-domain-verification) | [Get Apple Pay domain](/api-reference/public/get-apple-pay-domain) | | List drop zones | [List drop zones](/api-reference/store/list-drop-zones) | [List public drop zones](/api-reference/public-drop-zones/an-array-of-available-checkout-and-order-confirmation-drop-zones-public) | ## Do not mix surfaces on a bundle cart Pick one surface for each cart lifecycle. Unsubscribing a bundle line produces different results. The Public SDK API reprices the bundle's child items and releases the subscription-derived price lock. The Checkout API clears the subscription plan fields but does not reprice the bundle children or release that price lock. Moving a bundle cart between surfaces can therefore leave child pricing in a state that neither surface would have produced on its own. ## Understand the `stable` alias `/api/public/stable/` is a live alias for the operations mounted from the same public route set as `/api/public/v2025-06/`. The FairShare SDK uses the alias for realtime authentication. The alias is not blanket. The video-analytics operation uses a separate versioned route and has no `stable` twin. The 18 operations in this specification that sit outside `/api/public/v2025-06/` are also not rewritten through the alias. Use the explicit version when you need a pinned contract. Use `stable` only when you deliberately want to follow the current Public SDK API version. ## Next steps Build a cart directly through REST. Inspect the operations used by the FairShare SDK. Follow a product-to-order workflow on the Checkout API. Use the SDK methods backed by the Public SDK API.