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. A few cart operations, such as setting the volume rep, also need a Bearer token. See Know which cart operations need a token.
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. Send the recipient’s full name in name: this endpoint keeps name and drops first_name and last_name.
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. A card is attached to the cart itself, and completing the checkout charges it. See the Cart payment endpoints reference for tokenization, 3D Secure, and the wallet flows (Apple Pay, PayPal, and others). If your payment flow returns a payment reference, carry it into the next step as the payment_uuid query parameter. To try the whole flow without a real card, see Place a test order.
9

Complete the checkout

Turn the cart into an order with POST /api/checkout/v2026-04/carts/{cart_token}/complete. If the payment step returned a payment reference, pass it as the payment_uuid query parameter. Always send an Idempotency-Key header so a retried request never places a second order. A successful call returns 200 with the completed order.The cart lists its checkout agreements under agreements. Accept every agreement whose required is true by passing its id in accepted_agreement_ids, in the JSON request body; a checkout without them is refused with 422.
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.

​
Place a test order

A new company comes with a test card gateway, so you can prove the whole flow works before the merchant’s payments are approved, with no browser and no real card. The test gateway approves every charge and never sends the card to a processor, so no money moves. Everything else treats it as a real order: it sends the same order webhooks and order emails, and any back office, sales channel or droplet already connected sees it. The only test marker is on its payment, test_transaction true in the order webhook’s payments. Give the cart an email address you control, tell the merchant which order was the test, and refund it afterwards (below). The test gateway is in place once the merchant has confirmed the company’s signup. Build a cart through the shipping step above, with an email and an address, then:
  1. Check the cart offers only the test gateway. Read the cart and look at available_payment_methods. Go on only if every entry has type credit_card, test true, and bogus_gateway true, and take that entry’s uuid. If any entry is a live payment method, stop: a charge could reach a real processor. An empty list means the company has no payment account yet.
  2. Get a test card token. Call POST /api/v202506/payments/tokenize_card with test card details under credit_card: a test number such as 4242424242424242 and any future expiry month and year. Never send a real card to this endpoint: it takes the full card number with no Bearer token. It checks the card locally and returns the token under transaction.payment_method.token.
  3. Attach the card to the cart. Call PUT /api/payments/v2026-04/carts/{cart_token}/payment_method with type credit_card, the card under payment_method, and the test gateway’s uuid as payment_account, so the charge can only go to that account. A successful call returns 201. Under payment_method, put the step 2 token in token, and copy the card’s details from the same step 2 payment_method: full_name into card_holder, last_four_digits into last_four, first_six_digits into bin, card_network as it is, and month and year into exp_month and exp_year. Keep token_provider as vgs, even though this token didn’t come from VGS: vgs is the only provider a card accepts.
  4. Complete the checkout with the cart’s required agreements in accepted_agreement_ids and no payment_uuid. A successful call returns 200 with the order.
If the company has no payment account yet, complete is refused with 422, and the error’s code is payment_account_unavailable. No money moves. When you’ve checked the order, refund it in full and cancel it with POST /api/refunds, using the order’s numeric id from the order response, type all and cancel_order true. This needs the merchant’s Bearer token with permission to update refunds; no cart-token route cancels an order. The refund and the cancellation send their own order webhooks, and customer emails where the company has them turned on.
  • 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.
  • Read Checkout for how Fluid’s hosted checkout handles shipping, tax and rep attribution.