Skip to main content
Fluid hosts a full checkout, but you can also drive one yourself. The checkout surface exposes every step of a purchase as a cart operation, so you can build a bespoke storefront, embed checkout in your own app, or place orders on behalf of a rep. This guide walks the flow end to end: find a product, create a cart, add items, capture the buyer’s details, price shipping, take payment, and turn the cart into an order. The flow is built for direct-sales commerce — a cart can carry rep attribution, subscription line items, and enrollment context alongside ordinary products.
This guide covers a direct Checkout API integration. If you use the @fluid-app FairShare SDK, see Choosing a cart surface for its Public SDK API workflow.

​
Base URL and authentication

Every request goes to https://api.fluid.app. The checkout surface is versioned: paths sit under /api/checkout/v2026-04/. The cart operations in this flow are scoped by the cart_token in the path and need no company Bearer token. Creating a cart, querying a product, and retrieving a finished order are also public operations.
The create-cart response returns the cart_token used in every cart-level path. Treat it as a secret and send it only to Fluid.

​
The checkout flow

1

Find a product and a variant

A cart is built from product variants, so you start by resolving the variant_id you want to sell. Query a single product on the checkout surface with POST /api/checkout/v2026-04/products/{id}, passing the shop under metadata.fluid_shop. The {id} segment accepts a product id or slug.
The response lists the product’s purchasable variants; see the Query product endpoint reference for its full shape. To browse or search the whole catalog instead of fetching one product, use the Storefront products API, documented under the Storefront endpoints reference.
2

Create a cart

Create the cart with POST /api/checkout/v2026-04/carts. The body requires fluid_shop (the company subdomain) and country_code (an ISO country code). You can seed the cart with an items array in the same call — each item requires a variant_id and a quantity — and attach rep attribution under attribution.
Creating a cart is a public operation — it needs no Bearer token. A successful call returns the cart, including the cart_token you pass to every subsequent step. A body that fails validation — for example a missing country_code — returns 422.
Store the returned cart_token in your application state. It identifies the cart for the rest of the flow.
3

Add and adjust line items

Add more items after creation with POST /api/checkout/v2026-04/carts/{cart_token}/items. The body takes an items array. For a new line, provide its variant_id and quantity. Mark an item as a subscription by setting subscription to true and naming a subscription_plan_id. See the endpoint reference for the alternative batch shapes.
You can inspect the cart at any time with GET /api/checkout/v2026-04/carts/{cart_token}, which returns the current items, totals, and available shipping methods.
4

Capture the buyer's contact details

Attach the buyer’s contact information with PATCH /api/checkout/v2026-04/carts/{cart_token}. The body accepts email, phone, and the marketing opt-ins email_marketing and sms_marketing.
5

Set the shipping address

Set the address with POST /api/checkout/v2026-04/carts/{cart_token}/address. The body requires a type — one of ship_to, bill_to, or both — and carries the address fields under an address object.
Setting the address triggers a full recalculation of tax, shipping, and totals, so the cart you get back reflects the destination. Re-read the cart to see the refreshed available shipping methods.
6

Select a shipping method

Once the cart has an address, choose one of its available methods with PUT /api/checkout/v2026-04/carts/{cart_token}/shipping, passing the shipping_method_id. Selecting a shipping method is idempotent — selecting the same one again is a no-op.
7

Apply a discount code (optional)

Apply a promotion with POST /api/checkout/v2026-04/carts/{cart_token}/discount, passing the discount_code. Applying a discount is not idempotent — applying the same code twice returns an error.
8

Collect payment

Card capture and tokenization happen on Fluid’s cart payment surface, which authenticates with the cart token in the path — no Bearer token — and returns a payment reference. See the Cart payment endpoints reference for tokenization, 3D Secure, and the wallet flows (Apple Pay, PayPal, and others). Carry the resulting reference into the next step as the payment_uuid query parameter.
9

Complete the checkout

Turn the cart into an order with POST /api/checkout/v2026-04/carts/{cart_token}/complete. 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. A successful call returns 200 with the completed order.
Completion is final. Once the cart converts to an order it is locked, and any further mutation returns 410. Do not reuse the cart_token after a successful checkout — start a new cart for the next purchase.
10

Retrieve the order

Read the order back with GET /api/checkout/v2026-04/orders/{token}, using the order token from the completion response. This endpoint is public, so you can show an order-confirmation page without a Bearer token. The response carries the order’s token and its human-facing order_number.
  • Cart payment — card tokenization, 3D Secure, and wallet payments live on the cart payment surface; see the Cart payment endpoints reference.
  • Storefront — browse and search the product catalog on the Storefront endpoints reference.
  • Subscriptions — the checkout surface also manages the subscriptions a cart creates; see the subscription operations in the reference.

​
Next steps

  • Browse the Create a cart endpoint reference for full request and response schemas.
  • Create a cart, add an item, and read it back to confirm your token handling before wiring up payment.