> ## 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. # Sets cart payment method > 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 PayPalPaymentResponse (decrypted PayPal flow) depending on the cart's payment account configuration. ## OpenAPI ````yaml /api-reference/public-v2025-06.yaml post /api/public/v2025-06/commerce/carts/{cart_token}/payment_methods/{type} openapi: 3.1.0 info: title: Fluid Public SDK API description: >- **Fluid Public SDK API — the REST surface behind the `@fluid-app` FairShare SDK.** This is what the SDK calls on your behalf from the browser. Read it to understand what the SDK sends and receives, to verify a payload, or to call an SDK-backed endpoint directly. It also owns the browser-side platform surface that exists nowhere else: event tracking, lead capture, media and playlists, embeddable widgets, forms, sessions, settings, browser fingerprinting, affiliate lookup, root themes, and Pusher auth. Its cart endpoints (`/api/public/v2025-06/commerce/carts/…`) are **session-aware**: they accept `fluid_session` and populate visitor session and rep attribution on the cart. They also cover enrollment-pack carts (`…/enroll`, `…/enrollment`) and payment-gateway callbacks, which the Checkout API does not. Most browser and cart operations require no bearer token. The cart token in the path scopes cart requests. Synchronizing an authenticated customer, overriding cart item prices, and overriding cart item volumes require a bearer token. **Building a checkout from scratch, server-side? Use the Fluid Checkout API (`checkout-v2026-04`) instead** — it is the forward surface and the only one with customer accounts and subscription management. See [Choosing a cart surface](https://docs.fluid.app/api/choosing-a-cart-surface) for the operation map and boundary. Note: the version label names this spec, not a single path prefix. Endpoints here live under `/api/public/v2025-06/`, its partial `/api/public/stable/` alias, `/api/public/`, `/api/v202506/carts/`, and the cart price-override path under `/api/carts/`. version: v2025-06 contact: email: support@fluid.app license: name: Proprietary identifier: LicenseRef-Proprietary servers: - url: https://api.fluid.app - url: https://{company}.fluid.app description: Production server with company subdomain variables: company: default: myco description: Company subdomain security: [] tags: - name: carts description: >- Create, read, and mutate session-aware carts (items, address, country, language, discounts, shipping method, payment method, magic-link login, checkout). - name: checkout description: Checkout-started event emitted when a shopper enters the checkout flow. - name: commerce description: Admin-authenticated cart price overrides. - name: orders description: Public order lookup by token, including earned loyalty points. - name: product description: Localized product lookup by slug for storefronts and themes. - name: enrollment-packs description: Enrollment pack lookup by slug, for enrollment-pack carts. - name: payment description: Klarna session creation and updates for a cart. - name: paypal description: PayPal order creation, authorization, and shipping callbacks for a cart. - name: events description: Browser-side event ingestion — page visits, URL visits, and lead capture. - name: session description: Visitor session creation, the basis of cart and rep attribution. - name: fingerprint description: Browser fingerprint registration used to link sessions to a visitor. - name: lead description: Lead capture from storefront and theme forms. - name: forms description: Public form retrieval, password verification, and response submission. - name: media description: Media lookup by slug and video analytics events. - name: playlist description: Playlist (library) lookup by slug. - name: widgets description: Embeddable storefront widgets — banners, carts, chats, and popups. - name: page description: Page-visit tracking for storefront and theme pages. - name: url description: Short-link and URL visit tracking. - name: settings description: >- Company storefront settings the SDK reads at boot — company, cart, and affiliate configuration. - name: affiliate description: Affiliate lookup used to resolve a rep from a share link or handle. - name: root-themes description: Root theme catalog backing the theme editor and storefront rendering. - name: public description: >- Public utilities — health checks, Pusher auth, Apple Pay domain verification, leaderboards, and cart item volumes. - name: public-drop-zones description: >- Active checkout and order-confirmation drop zones used internally by the FairShare SDK. Direct REST integrations should use checkout-v2026-04. paths: /api/public/v2025-06/commerce/carts/{cart_token}/payment_methods/{type}: post: tags: - carts summary: Sets cart payment method description: > 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 PayPalPaymentResponse (decrypted PayPal flow) depending on the cart's payment account configuration. operationId: public_v2025_06_cart_payment_method-update parameters: - name: cart_token in: path required: true schema: type: string - name: type in: path description: > Payment method type. Core types: credit_card, affirm, bread, paypal, apple_pay, klarna. Platform-specific types follow the pattern {method}_{platform} (e.g. wechat_citcon, pix_dlocal, bancontact_ppro). required: true schema: type: string x-extensible-enum: - credit_card - affirm - bread - paypal - apple_pay - klarna - name: jwt in: query required: false description: JWT token for authenticated checkout schema: type: string - name: payment_method_id in: query required: false description: > Saved payment method ID. When provided with a jwt query param, uses an existing saved payment method instead of creating a new one. The request body is not required in this flow. schema: type: integer requestBody: required: false content: application/json: schema: type: object properties: payment_method: $ref: '#/components/schemas/PaymentMethodRequest' billing_address: $ref: '#/components/schemas/BillingAddress' use_customer_payment_method: type: boolean description: > When true, payment_method_id resolves against the customer's saved methods (via jwt). When false or omitted, it resolves against the fluid pay account. payment_account: type: - string - 'null' description: Payment account identifier device_data: type: - string - 'null' description: Braintree fraud detection fingerprint responses: '201': description: Payment method set successfully content: application/json: schema: oneOf: - $ref: '#/components/schemas/CreditCardPaymentResponse' - $ref: '#/components/schemas/PayPalPaymentResponse' - $ref: '#/components/schemas/KlarnaPaymentResponse' - $ref: '#/components/schemas/EmptyPaymentResponse' '404': description: Cart not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '410': $ref: '#/components/responses/ProcessedCartResponse' security: [] components: schemas: PaymentMethodRequest: type: object description: > Fields vary by payment type. Required per type: credit_card — token, token_provider, exp_month, exp_year; paypal — order_id (and optionally token); klarna — authorization_token, session_id; affirm, bread, apple_pay — token. properties: token: type: string description: >- Payment token (credit_card via VGS, affirm, bread, apple_pay) or PayPal authorization ID token_provider: type: string description: Token provider (e.g. "vgs" for credit cards) exp_month: type: string exp_year: type: string order_id: type: string description: PayPal order ID authorization_token: type: string description: Klarna authorization token session_id: type: string description: Klarna session ID sdk_type: type: string description: SDK variant (e.g. "braintree" for Braintree PayPal flow) BillingAddress: type: object required: - name - address1 - city - state - postal_code - country_code properties: id: type: integer description: Optional supplemental field; matches an existing saved address name: type: string address1: type: string address2: type: - string - 'null' city: type: string state: type: string postal_code: type: string country_code: type: string CreditCardPaymentResponse: type: object required: - card properties: card: type: object required: - token - active - default - test - fluid properties: active: type: boolean address_id: type: - integer - 'null' billing_address: type: - object - 'null' properties: name: type: - string - 'null' address1: type: - string - 'null' address2: type: - string - 'null' address3: type: - string - 'null' city: type: - string - 'null' state: type: - string - 'null' postal_code: type: - string - 'null' country_code: type: - string - 'null' subdivision_code: type: - string - 'null' phone: type: - string - 'null' additionalProperties: false card_network: type: - string - 'null' cvv_token: type: - string - 'null' default: type: boolean email: type: - string - 'null' fingerprint: type: - string - 'null' first_six_digits: type: - string - 'null' fluid: type: boolean fluid_pay_account_id: type: - integer - 'null' full_name: type: - string - 'null' last_four_digits: type: - string - 'null' member_id: type: - string - 'null' format: uuid month: type: - integer - 'null' number: type: - string - 'null' test: type: boolean token: type: string token_provider: type: - string - 'null' updated_at: type: string format: date-time created_at: type: string format: date-time user_id: type: - integer - 'null' uuid_v7: type: string format: uuid year: type: - integer - 'null' vgs_card_id: type: - string - 'null' description: VGS vault card ID, present when dual-vault registration succeeds customer_id: type: - integer - 'null' additionalProperties: false meta: type: - object - 'null' additionalProperties: false PayPalPaymentResponse: oneOf: - type: object required: - order_id properties: order_id: type: string description: Standard PayPal flow - type: object required: - transaction_id properties: transaction_id: type: string description: Braintree SDK PayPal flow KlarnaPaymentResponse: type: object required: - authorization_token properties: authorization_token: type: string EmptyPaymentResponse: type: object description: >- Empty response body for payment methods that do not return provider details. additionalProperties: false ErrorResponse: type: object required: - error_message - errors - meta properties: error_message: type: string errors: $ref: '#/components/schemas/ErrorBag' meta: $ref: '#/components/schemas/ErrorMeta' ErrorBag: description: >- Validation errors keyed by field, a list of errors, a single error message, or null when no structured error details are available. anyOf: - type: string - type: array items: $ref: '#/components/schemas/ErrorValue' - type: object additionalProperties: $ref: '#/components/schemas/ErrorValue' - type: 'null' ErrorMeta: type: object properties: request_id: type: - string - 'null' timestamp: type: string format: date-time shop_url: type: - string - 'null' cart: anyOf: - $ref: '#/components/schemas/Cart' - type: 'null' additionalProperties: false LockedCartErrorResponse: type: object additionalProperties: false required: - error_message - errors - meta properties: error_message: type: string errors: $ref: '#/components/schemas/ErrorBag' meta: type: object additionalProperties: false required: - request_id - timestamp - shop_url - cart properties: request_id: type: - string - 'null' timestamp: type: string format: date-time shop_url: type: string cart: $ref: '#/components/schemas/Cart' ErrorValue: description: A validation or API error value. anyOf: - type: string - type: array items: type: string - type: object additionalProperties: $ref: '#/components/schemas/JsonValue' Cart: type: object additionalProperties: false properties: id: type: integer cart_token: type: string state: type: string state_revision: type: integer format: int64 minimum: 0 description: Monotonic ordering marker for published cart snapshots. email: type: - string - 'null' phone: type: - string - 'null' language_iso: type: - string - 'null' currency_code: type: string currency_symbol: type: string currency_decimal_places: type: integer type: type: - string - 'null' buyer_rep_id: type: - integer - 'null' customer_id: type: - integer - 'null' enrollment_pack_id: type: - integer - 'null' email_marketing: type: - boolean - 'null' sms_marketing: type: - boolean - 'null' processed: type: boolean valid_for_checkout: type: boolean valid_for_checkout_pre_payment: type: boolean vault_without_charge: type: boolean payment_method_auto_assignable: type: boolean requires_payment_method: type: boolean requires_3ds: type: boolean immutable_items: type: boolean digital_only: type: boolean points_enabled: type: boolean messages: anyOf: - type: object additionalProperties: $ref: '#/components/schemas/JsonValue' - type: 'null' metadata: anyOf: - type: object additionalProperties: $ref: '#/components/schemas/JsonValue' - type: 'null' cv_total: type: - string - 'null' format: decimal qv_total: type: - string - 'null' format: decimal amount_total: type: number amount_total_in_currency: type: string sub_total: type: number sub_total_in_currency: type: string tax_total: type: number tax_exempt: type: boolean tax_total_in_currency: type: string tax_total_for_display: type: string inclusive_shipping_tax: type: number shipping_total: type: number shipping_total_in_currency: type: string shipping_total_for_display: type: string discount_total: type: number discount_total_in_currency: type: string subtotal_after_discounts: type: number subtotal_after_discounts_in_currency: type: string price_inclusive_of_tax: type: boolean price_inclusive_tax_name: type: - string - 'null' totals: type: object additionalProperties: false required: - gross_subtotal - gross_subtotal_in_currency - net_subtotal - net_subtotal_in_currency - item_tax - item_tax_in_currency - shipping_net - shipping_net_in_currency - shipping_tax - shipping_tax_in_currency - total_tax - total_tax_in_currency - price_inclusive_of_tax - tax_label description: >- Display-ready totals breakdown sourced from Commerce::Totals (STU2-2580). Decomposes the inclusive-tax figures so clients render the net subtotal, item tax, shipping net and shipping VAT without re-deriving them. Each money component carries a raw boundary-rounded decimal string plus its currency-formatted `_in_currency` sibling. properties: gross_subtotal: type: string description: Catalog sum of line-item prices (customer display). gross_subtotal_in_currency: type: string net_subtotal: type: string description: Items subtotal excluding embedded item tax. net_subtotal_in_currency: type: string item_tax: type: string description: Embedded tax attributable to the items. item_tax_in_currency: type: string shipping_net: type: string description: Shipping charge excluding embedded shipping tax. shipping_net_in_currency: type: string shipping_tax: type: string description: Embedded tax attributable to shipping. shipping_tax_in_currency: type: string total_tax: type: string description: Combined item and shipping tax. total_tax_in_currency: type: string price_inclusive_of_tax: type: boolean description: Whether catalog prices include tax. tax_label: type: - string - 'null' description: The resolved tax-line label (e.g. "VAT"), or null. enrollment_fee: type: - number - string enrollment_fee_in_currency: type: string transaction_fee: type: - number - string transaction_fee_in_currency: type: string shipping_discount: type: number discount_codes: type: array items: type: string product_discount_codes: type: array items: type: string shipping_discount_codes: type: array items: type: string customer_total_points: type: integer customer_total_points_in_currency: type: string points_applied: type: integer points_applied_amount_in_currency: type: string remaining_customer_points: type: integer remaining_customer_points_amount_in_currency: type: string remaining_cart_amount_after_points: type: number remaining_cart_amount_after_points_in_currency: type: string max_applicable_points: type: integer total_creditable_points: type: integer shipping_address: anyOf: - type: object additionalProperties: $ref: '#/components/schemas/JsonValue' - type: 'null' billing_address: anyOf: - type: object additionalProperties: $ref: '#/components/schemas/JsonValue' - type: 'null' discount_breakdown: type: object additionalProperties: false properties: internal_discounts: type: number external_discounts: type: number total_discounts: type: number external_discount: type: object additionalProperties: $ref: '#/components/schemas/JsonValue' buyer_rep: type: - object - 'null' additionalProperties: false properties: id: type: integer email: type: string full_name: type: string image_url: type: - string - 'null' external_id: type: - string - 'null' volume_rep: type: - object - 'null' additionalProperties: false properties: id: type: integer email: type: string full_name: type: string image_url: type: - string - 'null' available_shipping_methods: type: array items: type: object additionalProperties: false properties: id: type: - string - integer title: type: string price: type: number delivery_time_estimate: type: - string - 'null' price_label: type: - string - 'null' available_payment_methods: type: array items: type: object additionalProperties: $ref: '#/components/schemas/JsonValue' payment_account: anyOf: - type: object additionalProperties: $ref: '#/components/schemas/JsonValue' - type: 'null' shipping_method: type: - object - 'null' additionalProperties: false properties: id: type: string name: type: string payment_method: anyOf: - type: object additionalProperties: $ref: '#/components/schemas/JsonValue' - type: 'null' items: type: array items: $ref: '#/components/schemas/CartItem' ship_to: $ref: '#/components/schemas/CartAddress' bill_to: anyOf: - type: object additionalProperties: $ref: '#/components/schemas/JsonValue' - type: 'null' attribution: anyOf: - type: object additionalProperties: $ref: '#/components/schemas/JsonValue' - type: 'null' agreements: type: array items: type: object additionalProperties: false properties: id: type: integer title: type: string show_at_checkout: type: boolean default_checked: type: boolean show_path: type: string enrollment_pack_id: type: - integer - 'null' required: type: boolean country: $ref: '#/components/schemas/CartCountry' company: $ref: '#/components/schemas/CartCompany' enrollment_pack: anyOf: - type: object additionalProperties: $ref: '#/components/schemas/JsonValue' - type: 'null' recurring: type: array items: type: object additionalProperties: false required: - subtotal - subtotal_in_currency - interval - interval_unit - interval_unit_identifier - subtotal_for_display - start_date properties: subtotal: type: number subtotal_in_currency: type: string interval: type: integer interval_unit: type: string interval_unit_identifier: type: string enum: - day - week - month - year subtotal_for_display: type: string start_date: type: string JsonValue: description: >- Any valid JSON value for provider, integration, theme, metadata, or other dynamic payloads whose keys are not fixed by the API contract. anyOf: - type: string - type: number - type: boolean - type: 'null' - type: array items: $ref: '#/components/schemas/JsonValue' - type: object additionalProperties: $ref: '#/components/schemas/JsonValue' CartItem: type: object additionalProperties: false properties: id: type: integer title: type: string quantity: type: integer price: type: string price_in_currency: type: string discount_amount: type: string discount_amount_in_currency: type: string tax: type: string tax_in_currency: type: string cv: type: string format: decimal qv: type: string format: decimal cv_total: type: string format: decimal qv_total: type: string format: decimal total: type: string total_in_currency: type: string line_total_in_currency: type: string total_after_discounts: type: string total_after_discounts_in_currency: type: string line_total_after_discounts_in_currency: type: string unit_price_display_authoritative: type: boolean enrollment_pack_id: type: - integer - 'null' subscription: type: boolean subscription_plan_id: type: - integer - 'null' subscription_plans: type: array items: type: object additionalProperties: $ref: '#/components/schemas/JsonValue' subscription_only: type: - boolean - 'null' subscription_interval: type: - integer - 'null' subscription_interval_unit: type: - string - 'null' subscription_interval_unit_identifier: type: - string - 'null' subscription_price: type: - string - number - 'null' subscription_price_in_currency: type: - string - 'null' subscription_start: type: - string - 'null' subscribe_and_save: type: - string - number - 'null' subscribe_and_save_in_currency: type: - string - 'null' subscribe_and_save_for_display: type: - string - 'null' display_to_customer: type: boolean metadata: anyOf: - type: object additionalProperties: $ref: '#/components/schemas/JsonValue' - type: 'null' image_url: type: - string - 'null' free_item: type: boolean allow_subscription: type: boolean enrollment: type: boolean errors: type: array items: type: string creditable_points: type: integer product: type: object additionalProperties: $ref: '#/components/schemas/JsonValue' variant: type: - object - 'null' additionalProperties: false properties: id: type: integer title: type: - string - 'null' display_name: type: - string - 'null' image_url: type: - string - 'null' image_path: type: - string - 'null' sku: type: - string - 'null' primary_image: type: - string - 'null' price: type: - number - string - 'null' price_in_currency: type: string currency_code: type: - string - 'null' options: type: array items: type: object additionalProperties: false properties: title: type: string value: type: string physical: type: - boolean - 'null' unit_of_size: type: - string - 'null' height: type: - number - 'null' width: type: - number - 'null' length: type: - number - 'null' unit_of_weight: type: - string - 'null' weight: type: - string - 'null' hs_code: type: - string - 'null' bundled_items: type: - array - 'null' items: type: object additionalProperties: $ref: '#/components/schemas/JsonValue' product_title: type: - string - 'null' CartAddress: type: - object - 'null' additionalProperties: false properties: id: type: integer name: type: - string - 'null' address1: type: - string - 'null' address2: type: - string - 'null' address3: type: - string - 'null' city: type: - string - 'null' state: type: - string - 'null' subdivision_code: type: - string - 'null' postal_code: type: - string - 'null' country_code: type: - string - 'null' phone: type: - string - 'null' country_num_code: type: - integer - 'null' default: type: boolean CartCountry: type: - object - 'null' additionalProperties: false properties: id: type: integer name: type: string iso: type: string iso_name: type: string iso3: type: string currency_code: type: string currency_symbol: type: string province_required: type: boolean tax_enabled: type: - boolean - 'null' price_inclusive_of_tax: type: - boolean - 'null' price_inclusive_tax_name: type: - string - 'null' tax_standard_rate: type: - number - 'null' description: Standard tax rate (percent) used for inclusive-pricing countries CartCompany: type: object additionalProperties: false properties: id: type: integer name: type: string favicon_url: type: - string - 'null' primary_domain_hostname: type: - string - 'null' subdomain: type: - string - 'null' logo_url: type: - string - 'null' fluid_shop: type: - string - 'null' collect_phone: type: boolean require_phone: type: boolean require_billing_zip: type: boolean checkout_primary_button_color: type: - string - 'null' checkout_primary_text_color: type: - string - 'null' checkout_secondary_button_color: type: - string - 'null' checkout_secondary_text_color: type: - string - 'null' order_on_behalf: type: boolean reward_points_enabled: type: boolean reward_points_apply_to_subtotal: type: boolean reward_points_label_singular: type: string reward_points_label_plural: type: string collect_sms_marketing: type: boolean collect_email_marketing: type: boolean bundle_subscriptions: type: boolean isolated_payment_tokens: type: boolean description: >- When true, this company's payment tokens and customer profile are isolated from the shared FluidPayAccount wallet. Clients must use customer-scoped PM/address mutation routes. kount_environment: type: string enum: - sandbox - production example: sandbox description: >- Per-merchant Kount environment. Used by the checkout DDC initializer to pick TEST vs PROD. kount_client_id: type: - string - 'null' example: '150953359757648' description: >- Per-merchant Kount Client ID (MID) for enterprise merchants. Null for portfolio merchants. responses: ProcessedCartResponse: description: >- The cart is locked and can no longer be modified. Cart-mutation endpoints return this when the cart has already been processed (converted to an order) or, for enrollment carts, is in an authorized payment state. The body carries the full cart plus the store URL so the client can display the locked cart and redirect. content: application/json: schema: $ref: '#/components/schemas/LockedCartErrorResponse' ````