Choosing a cart surface: Checkout API vs. Public SDK API

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 unsubscribing a bundle line through the wrong Checkout API operation leaves its pricing behind. Use one surface for each cart lifecycle. Follow the generated reference links below for the current request and response contracts.

​

Choose a surface

​

Know which cart operations need a token

A shopper on your storefront has no account and no secret, and code that runs in their browser can’t keep one. So the cart doesn’t ask for a Bearer token. The cart_token that creating a cart returns is the credential instead: only the browser or app that created the cart holds it, and it opens only that cart. Anyone holding a cart token can shop with that cart. The operations that change what the buyer pays, who gets credit for the sale, or whose saved data is on the cart need a Bearer token as well.

​

What the cart token alone allows

On both surfaces, a request with only the cart token can:

• Create a cart and add, change, subscribe, or remove line items.
• Set the buyer’s email and phone, the address, and the shipping method.
• Apply or remove a promo code, and change the cart’s country or language.
• Send and confirm a sign-in link, and sign the buyer out.
• Complete the cart.

On the Checkout API, the cart token also covers the email and SMS marketing opt-ins and the automatic points setting.

​

Fields the cart token can’t change

Some fields are accepted in a request body but ignored when the request has no token that allows them. The request still succeeds, so check the response rather than assuming the value was applied.

​

Operations that need a Bearer token

A token for a different company never unlocks a cart. Keep company API tokens on your server. Never send one from storefront code.

​

Distinguish the two v2025-06 APIs

Two unrelated APIs carry the same version label: 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.

​

Do not mix surfaces on a bundle cart

​

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

For how checkout and rep credit work behind either surface, see Checkout and FairShare attribution.