> ## 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. # Show a cart > Returns the current cart — its line items, totals, selected and available shipping methods, addresses, and applied discounts. Read-only; no side effects. Access is scoped by the `cart_token` in the path — the endpoint itself does not require authentication. In Fluid's recommended server-side integration you send a company bearer token (`Authorization: Bearer `) on every cart request; it is optional at the endpoint but drives cart attribution and wallet resolution for companies using isolated payment tokens (see the Headless Commerce guide). Returns `404` when the token does not resolve to a cart. ## OpenAPI ````yaml /api-reference/checkout-v2026-04.yaml get /api/checkout/v2026-04/carts/{cart_token} openapi: 3.1.0 info: title: Fluid Checkout API description: >- **Fluid Checkout API — for building a checkout directly against REST.** Use this surface if you are integrating server-to-server or building your own checkout UI. It covers the full order lifecycle (cart → address → shipping → discount → complete → order) plus the logged-in customer's account: saved addresses, saved payment methods, order history, loyalty points, and subscription management (pause, resume, skip, cancel, retry). **The cart token in the URL scopes cart access** — creating a cart, adding items, applying a discount, and completing a cart need no bearer token. Among the cart operations, a Bearer token is required only for `carts/{cart_token}/sync`, `carts/{cart_token}/volume_rep`, and `carts/{cart_token}/discount/manual`. Off the cart, a token is required for everything under `customers/me` and `subscriptions`, and for the store and directory lookups (`store/config`, `store/languages`, `reps`, `users`) and `subscription_bundles`. `store/countries` accepts a token but does not require one — it returns the same list either way. **If you are using the `@fluid-app` FairShare SDK in a theme or storefront, you are not calling this surface** — the SDK calls the Fluid Public SDK API (`public-v2025-06`). Do not mix the two against one cart: they share the same cart records and services, but their request shapes differ. See [Choosing a cart surface](https://docs.fluid.app/api/choosing-a-cart-surface) for the operation map and boundary. version: v2026-04 contact: email: support@fluid.app license: name: Proprietary identifier: LicenseRef-Proprietary servers: - url: https://api.fluid.app security: [] tags: - name: carts description: >- Create, read, and mutate checkout carts (email, address, country, language, shipping, recalculation, completion). - name: cart-auth description: >- Cart-scoped customer authentication — magic-link challenge, verification, identity, and logout. - name: cart-discount description: >- Apply, list, and remove cart discount codes, including admin manual discounts. - name: cart-items description: Add, update, and remove line items on a cart. - name: cart-points description: Apply and remove loyalty points on a cart. - name: customers description: The authenticated customer's profile and company memberships. - name: customer-addresses description: The authenticated customer's saved shipping/billing addresses. - name: customer-orders description: The authenticated customer's order history. - name: customer-payment-methods description: The authenticated customer's saved payment methods and tokenization. - name: customer-points description: The authenticated customer's loyalty point balances. - name: directory description: Company rep and user directory lookups. - name: enrollments description: >- Public enrollment forms — retrieve a form and submit, update, or upload field answers. - name: orders description: Public order lookup by token. - name: products description: Public product queries for the storefront checkout. - name: store description: >- Store-level checkout configuration — countries, languages, address fields, agreements, drop zones, and Apple Pay domain verification. - name: subscriptions description: >- Manage subscriptions — pause, resume, skip, cancel, reactivate, retry, and failed-cycle waivers. - name: subscription-bundles description: List and create subscription bundles. paths: /api/checkout/v2026-04/carts/{cart_token}: get: tags: - carts summary: Show a cart description: > Returns the current cart — its line items, totals, selected and available shipping methods, addresses, and applied discounts. Read-only; no side effects. Access is scoped by the `cart_token` in the path — the endpoint itself does not require authentication. In Fluid's recommended server-side integration you send a company bearer token (`Authorization: Bearer `) on every cart request; it is optional at the endpoint but drives cart attribution and wallet resolution for companies using isolated payment tokens (see the Headless Commerce guide). Returns `404` when the token does not resolve to a cart. operationId: checkout_v2026_04_get_cart parameters: - name: cart_token in: path required: true description: Cart token schema: type: string - name: payment_methods_includes in: query required: false description: Comma-separated payment integration classes to include schema: type: string example: StripeIntegration,PaypalIntegration - name: payment_account in: query required: false description: Payment account selector used when rendering payment methods schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/CartResponse' '404': description: Cart not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: [] components: schemas: CartResponse: description: >- Cart response wrapper (CartBlueprinter with_associations view). Scalar totals, flags, and points are strictly typed; genuinely dynamic fields (metadata, processor-specific payment payloads) and nested associations (items, addresses, country, company) are typed as open pockets and tightened in follow-up work. type: object required: - cart - meta additionalProperties: false properties: cart: type: object additionalProperties: false properties: id: type: integer description: Numeric primary key of the cart row. cart_token: type: string description: > Opaque cart token. This is the value that scopes every subsequent cart operation as `{cart_token}`. Store it in your session after create-cart. state: type: string description: | Current lifecycle state of the cart. A completed cart is locked; mutations against it return `410`. state_revision: type: integer format: int64 minimum: 0 description: Monotonic ordering marker for published cart snapshots. type: type: - string - 'null' description: >- Cart type discriminator (e.g. enrollment vs standard); `null` when unset. email: type: - string - 'null' description: Buyer email captured on the cart; `null` until set. phone: type: - string - 'null' description: Buyer phone captured on the cart; `null` until set. language_iso: type: - string - 'null' description: >- ISO language code driving localized content; `null` when not set. currency_code: type: - string - 'null' description: >- ISO 4217 currency code the cart prices in; `null` until resolved. currency_symbol: type: string description: Display symbol for `currency_code` (e.g. `$`). currency_decimal_places: type: integer description: >- Number of fractional digits used when formatting money in this currency. customer_id: type: - integer - 'null' description: >- Id of the customer the cart is bound to, or `null` for an anonymous cart. buyer_rep_id: type: - integer - 'null' description: >- Id of the attributed buyer rep, or `null` when there is no attribution. enrollment_pack_id: type: - integer - 'null' description: Id of the enrollment pack seeded on the cart, or `null`. processed: type: boolean description: > `true` once the cart has been completed into an order. A processed cart is locked — further mutations return `410`. email_marketing: type: - boolean - 'null' description: >- Email marketing opt-in captured for the buyer; `null` when not asked. sms_marketing: type: - boolean - 'null' description: >- SMS marketing opt-in captured for the buyer; `null` when not asked. cv_total: type: - string - 'null' format: decimal qv_total: type: - string - 'null' format: decimal amount_total: type: number description: >- Grand total the buyer pays, in the cart currency (items + tax + shipping - discounts). sub_total: type: number description: Sum of line-item prices before tax, shipping, and discounts. tax_total: type: number description: Total tax on the cart. shipping_total: type: number description: Total shipping charge for the selected method. discount_total: type: number description: Total value of all applied discounts. subtotal_after_discounts: type: number description: >- Item subtotal after discounts are applied, before tax and shipping. transaction_fee: type: number description: Any transaction/processing fee added to the cart. enrollment_fee: type: - number - string - 'null' description: Enrollment fee applied to the cart, or `null` when none applies. inclusive_shipping_tax: type: number description: >- Portion of `shipping_total` that is embedded tax (tax-inclusive pricing). shipping_discount: type: number description: Discount applied specifically to shipping. remaining_cart_amount_after_points: type: number description: Amount still due after applying loyalty points. amount_total_in_currency: type: string sub_total_in_currency: type: string tax_total_in_currency: type: string shipping_total_in_currency: type: string discount_total_in_currency: type: string subtotal_after_discounts_in_currency: type: string transaction_fee_in_currency: type: string enrollment_fee_in_currency: type: string customer_total_points_in_currency: type: string points_applied_amount_in_currency: type: string remaining_customer_points_amount_in_currency: type: string remaining_cart_amount_after_points_in_currency: type: string tax_total_for_display: type: string shipping_total_for_display: type: string tax_exempt: type: boolean description: '`true` when the cart is exempt from tax.' digital_only: type: boolean description: '`true` when every line item is digital (no physical shipment).' immutable_items: type: boolean description: >- `true` when the cart's line items are locked and cannot be changed. points_enabled: type: boolean description: '`true` when loyalty points may be applied to this cart.' price_inclusive_of_tax: type: boolean description: '`true` when catalog prices already include tax.' requires_3ds: type: boolean description: >- `true` when the selected payment requires a 3D Secure challenge before completion. requires_payment_method: type: boolean description: >- `true` when a payment method must be supplied before the cart can complete. vault_without_charge: type: boolean description: >- `true` when a payment method is vaulted without an immediate charge. valid_for_checkout: type: boolean description: >- `true` when the cart passes all validations and can be completed into an order. valid_for_checkout_pre_payment: type: boolean description: >- `true` when the cart is valid up to the payment step (everything but payment is satisfied). payment_method_auto_assignable: type: boolean description: >- `true` when a payment method can be auto-assigned without buyer input. customer_total_points: type: integer points_applied: type: integer remaining_customer_points: type: integer max_applicable_points: type: integer total_creditable_points: type: integer 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. price_inclusive_tax_name: type: - string - 'null' payment_account: type: - string - 'null' discount_codes: type: array description: Discount codes currently applied to the cart. items: type: string product_discount_codes: type: array description: Applied discount codes that target products. items: type: string shipping_discount_codes: type: array description: Applied discount codes that target shipping. items: type: string buyer_rep: type: - object - 'null' additionalProperties: false properties: id: type: integer email: type: - string - 'null' full_name: type: - string - 'null' image_url: type: - string - 'null' external_id: type: - string - 'null' volume_rep: type: - object - 'null' additionalProperties: false properties: id: type: integer email: type: - string - 'null' full_name: type: - string - 'null' image_url: type: - string - 'null' shipping_method: type: - object - 'null' additionalProperties: false description: >- The shipping method currently selected on the cart; `null` when none is selected. properties: id: type: string description: >- Identifier of the selected shipping method (pass this as `shipping_method_id` when selecting). name: type: string description: Display name of the selected shipping method. discount_breakdown: type: object additionalProperties: false description: Breakdown of discount totals by source. properties: internal_discounts: type: number description: Total value of Fluid-internal discounts. external_discounts: type: number description: Total value of externally sourced discounts. total_discounts: type: number description: Combined discount total. available_shipping_methods: type: array description: > Shipping methods available for the cart's destination. Populated once a shipping address is set; select one by passing its `id` as `shipping_method_id`. items: type: object additionalProperties: false properties: id: type: - integer - string description: Identifier of the available shipping method. title: type: - string - 'null' description: Display name of the method. price: type: - number - string - 'null' description: Price of the method in the cart currency. delivery_time_estimate: type: - string - 'null' description: Human-readable delivery estimate, when available. price_label: type: - string - 'null' description: Preformatted price label for display. metadata: type: - object - 'null' additionalProperties: true messages: $ref: '#/components/schemas/JsonValue' payment_method: $ref: '#/components/schemas/CheckoutCartPaymentMethod' available_payment_methods: type: array items: $ref: '#/components/schemas/CheckoutAvailablePaymentMethod' external_discount: $ref: '#/components/schemas/CheckoutExternalDiscount' shipping_address: $ref: '#/components/schemas/CheckoutAddressData' billing_address: $ref: '#/components/schemas/CheckoutAddressData' items: type: array description: The cart's line items. items: $ref: '#/components/schemas/CheckoutCartItem' ship_to: description: Resolved shipping address on the cart; `null` when none is set. anyOf: - type: 'null' - $ref: '#/components/schemas/CheckoutAddress' bill_to: description: Resolved billing address on the cart; `null` when none is set. anyOf: - type: 'null' - $ref: '#/components/schemas/CheckoutAddress' attribution: $ref: '#/components/schemas/CheckoutAttribution' agreements: type: array items: $ref: '#/components/schemas/CheckoutAgreement' country: $ref: '#/components/schemas/CheckoutCountry' company: $ref: '#/components/schemas/CheckoutCompany' recurring: type: array items: $ref: '#/components/schemas/CheckoutCartRecurringItem' enrollment_pack: $ref: '#/components/schemas/CheckoutEnrollmentPack' meta: type: object additionalProperties: false properties: shop_url: type: string description: Base storefront URL for the cart's shop. checkout_url: type: string description: Hosted checkout URL for this cart. request_id: type: - string - 'null' description: Correlation id for the request, or `null`. timestamp: type: string format: date-time description: ISO 8601 time the response was generated. totals_stale: type: boolean description: >- Present (true) on the manual-discount response when cart recalculation failed after applying the discount. ErrorResponse: type: object additionalProperties: false required: - error_message - errors - meta properties: error_message: type: string errors: $ref: '#/components/schemas/ErrorBag' meta: $ref: '#/components/schemas/CheckoutMeta' 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' CheckoutCartPaymentMethod: description: >- Cart payment_method rendered by Commerce::CartBlueprinter::PaymentMethodFormatter. A closed polymorphic union across processors (CreditCard, Paypal, Affirm, Klarna, and a simple {id,type} fallback for all others). Nullable when the cart has no payment method. type: - object - 'null' additionalProperties: false properties: id: type: integer type: type: string description: Processor class (CreditCard, Paypal, Affirm, Klarna, Droplet, ...). payment_method_type: type: - string - 'null' card_network: type: - string - 'null' last_four: type: - string - 'null' exp_month: type: - string - integer - 'null' exp_year: type: - string - integer - 'null' logo_url: type: - string - 'null' status: type: - string - 'null' affirm_id: type: - string - integer - 'null' checkout_id: type: - string - integer - 'null' created: type: - string - integer - 'null' auth_expiration: type: - string - integer - 'null' currency: type: - string - 'null' amount: type: - number - string - 'null' session_id: type: - string - 'null' intent: type: - string - 'null' customer_details: type: object additionalProperties: true CheckoutAvailablePaymentMethod: description: >- Available payment method entry rendered by Commerce::CartsService#available_payment_methods_as_hash. Common envelope fields are strictly typed; processor-specific fields vary by gateway. type: object additionalProperties: true required: - id - uuid - type - name - image_url - test - sandbox - customer_details_schema properties: id: type: integer uuid: type: - string - 'null' type: type: string name: type: string image_url: type: - string - 'null' test: type: boolean sandbox: type: boolean collect_billing_address: type: boolean customer_details_schema: description: >- Map of required customer-info fields keyed by field name (e.g. phone, document_id); each gateway's required_customer_info_schema emits entries of {label, type, required} (empty object for most gateways). type: object additionalProperties: type: object additionalProperties: false required: - label - type - required properties: label: type: string type: type: string required: type: boolean supported_brands: type: array items: type: string token_provider: type: - string - 'null' tokenize_path: type: - string - 'null' bogus_gateway: type: boolean apple_pay: type: boolean apple_pay_recurring_supported: type: boolean apple_pay_merchant_identifier: type: - string - 'null' client_id: type: - string - 'null' merchant_id: type: - string - 'null' sdk_type: type: - string - 'null' decrypted_apple_pay_via_paypal: type: boolean integration_key: type: - string - 'null' CheckoutExternalDiscount: description: >- External (third-party) discount metadata rendered by Commerce::CartBlueprinter#external_discount_metadata. `sources` is a map keyed by discount-source identifier. type: - object - 'null' additionalProperties: false properties: total: type: number calculated_at: type: - string - 'null' format: date-time sources: type: object description: >- Map of discount-source id -> source entry. Each entry carries at least a rounded `amount`. additionalProperties: type: object additionalProperties: true properties: amount: type: - number - 'null' CheckoutAddressData: description: >- Cart shipping_address / billing_address snapshot rendered by AddressModel::Service#data (address_model.to_h). Distinct from CheckoutAddress - carries no id, country_num_code, or default. Nullable when the underlying snapshot is blank. type: - object - 'null' additionalProperties: false 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' CheckoutCartItem: description: >- Cart line item rendered by Commerce::CartItemBlueprinter (:cart view), including nested product and variant. type: object additionalProperties: false properties: id: type: integer description: Line-item id. Pass it as `{id}` to update or remove this line. title: type: - string - 'null' description: Display title of the line item. quantity: type: integer description: Quantity of the variant on this line. price: type: - number - string - 'null' description: Unit price of the line item in the cart currency. discount_amount: type: - number - string - 'null' description: Discount applied to this line. tax: type: - number - string - 'null' description: Tax attributable to this line. cv: type: - string - 'null' format: decimal qv: type: - string - 'null' format: decimal cv_total: type: - string - 'null' format: decimal qv_total: type: - string - 'null' format: decimal total: type: - number - string - 'null' description: Line total before discounts (unit price times quantity). total_after_discounts: type: - number - string - 'null' description: Line total after this line's discounts are applied. enrollment_pack_id: type: - integer - 'null' description: Enrollment pack this line belongs to, or `null`. subscription: type: - boolean - 'null' description: '`true` when this line is a subscription item.' display_to_customer: type: - boolean - 'null' description: >- `true` when the line is shown to the customer (bundle children may be hidden). image_url: type: - string - 'null' description: Image URL for the line item. price_in_currency: type: - string - 'null' description: Currency-formatted unit price for display. tax_in_currency: type: - string - 'null' description: Currency-formatted line tax for display. discount_amount_in_currency: type: - string - 'null' total_in_currency: type: - string - 'null' total_after_discounts_in_currency: type: - string - 'null' line_total_in_currency: type: - string - 'null' line_total_after_discounts_in_currency: type: - string - 'null' unit_price_display_authoritative: type: - boolean - 'null' free_item: type: - boolean - 'null' description: '`true` when the line is a free/gift item.' allow_subscription: type: - boolean - 'null' description: '`true` when this line may be converted to a subscription.' enrollment: type: - boolean - 'null' description: '`true` when the line is part of an enrollment.' creditable_points: type: - integer - 'null' description: Loyalty points this line can earn, or `null`. product_title: type: - string - 'null' description: Title of the underlying product. subscription_plan_id: type: - integer - 'null' description: >- Id of the subscription plan for a subscription line; `null` otherwise. subscription_only: type: - boolean - 'null' description: '`true` when the variant can only be purchased as a subscription.' subscription_interval: type: - integer - string - 'null' subscription_interval_unit: type: - string - 'null' subscription_interval_unit_identifier: type: - string - 'null' subscription_price: type: - number - string - 'null' subscription_price_in_currency: type: - string - 'null' subscription_start: type: - string - 'null' subscribe_and_save: type: - number - string - 'null' subscribe_and_save_in_currency: type: - string - 'null' subscribe_and_save_for_display: type: - string - 'null' metadata: type: - object - 'null' additionalProperties: true errors: type: array description: Per-item checkout errors (cart_item.item_checkout_errors). items: $ref: '#/components/schemas/CheckoutCartItemError' subscription_plans: type: array description: >- Subscription plans rendered by SubscriptionPlanBlueprinter (:cart_item view). items: $ref: '#/components/schemas/CheckoutCartItemSubscriptionPlan' bundled_items: type: array description: >- Bundle child selections (metadata-derived, customer-visible entries only in the :cart view). items: $ref: '#/components/schemas/CheckoutBundledItem' product: $ref: '#/components/schemas/CheckoutProduct' variant: $ref: '#/components/schemas/CheckoutVariant' CheckoutAddress: description: Resolved address on a cart (AddressBlueprinter default view). type: object properties: address1: type: string description: Primary street line of the address. address2: type: 'null' description: Second address line; always `null` in this view. address3: type: 'null' description: Third address line; always `null` in this view. city: type: string description: City / locality. country_code: type: string description: ISO 3166-1 alpha-2 country code (e.g. `US`). country_num_code: type: integer description: ISO 3166-1 numeric country code. default: type: boolean description: '`true` when this is the customer''s default address.' id: type: - integer - 'null' description: >- Persisted address id, or `null` for an unsaved/wallet-partial address. name: type: - string - 'null' description: >- Recipient name; `null` for wallet-partial addresses that are privacy-scrubbed until approval. phone: type: - string - 'null' description: Contact phone for the address; `null` when unset. postal_code: type: string description: Postal / ZIP code. state: type: string description: State / province / region. subdivision_code: type: 'null' description: ISO subdivision code; always `null` in this view. required: - address1 - address2 - address3 - city - country_code - country_num_code - default - id - name - phone - postal_code - state - subdivision_code additionalProperties: false CheckoutAttribution: description: >- Cart attribution rendered by AttributionBlueprinter. Emits `id` plus exactly one attribution-type key (the cart's attributable_type) whose value is the attributable_id. Nullable when the cart has no attribution. type: - object - 'null' additionalProperties: false properties: id: type: integer email: type: - integer - string - 'null' fluid_rep_id: type: - integer - string - 'null' external_id: type: - integer - string - 'null' share_guid: type: - integer - string - 'null' username: type: - integer - string - 'null' CheckoutAgreement: description: Checkout agreement rendered by AgreementBlueprinter (default view). type: object additionalProperties: false properties: id: type: integer title: type: - string - 'null' show_at_checkout: type: - boolean - 'null' default_checked: type: - boolean - 'null' show_path: type: - string - 'null' enrollment_pack_id: type: - integer - 'null' required: type: boolean description: >- Whether the agreement must be accepted at checkout (mirrors Agreement#required_on_checkout, coerced to a strict boolean). CheckoutCountry: type: object properties: currency_code: type: string currency_symbol: type: string id: type: integer iso: type: string iso3: type: string iso_name: type: string name: type: string price_inclusive_of_tax: type: boolean price_inclusive_tax_name: type: string province_required: type: boolean tax_enabled: type: - boolean - 'null' tax_standard_rate: type: - number - 'null' description: Standard tax rate (percent) used for inclusive-pricing countries required: - currency_code - currency_symbol - id - iso - iso3 - iso_name - name - price_inclusive_of_tax - price_inclusive_tax_name - province_required - tax_enabled - tax_standard_rate additionalProperties: false CheckoutCompany: type: object properties: bundle_subscriptions: 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' collect_email_marketing: type: boolean collect_phone: type: boolean collect_sms_marketing: type: boolean favicon_url: type: - string - 'null' fluid_shop: type: string id: type: integer isolated_payment_tokens: type: boolean 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 — the checkout app falls back to NEXT_PUBLIC_KOUNT_CLIENT_ID. logo_url: type: - string - 'null' name: type: string order_on_behalf: type: boolean primary_domain_hostname: type: string require_billing_zip: type: boolean require_phone: type: boolean reward_points_apply_to_subtotal: type: boolean reward_points_enabled: type: boolean reward_points_label_singular: type: string reward_points_label_plural: type: string subdomain: type: - string - 'null' required: - bundle_subscriptions - checkout_primary_button_color - checkout_primary_text_color - checkout_secondary_button_color - checkout_secondary_text_color - collect_email_marketing - collect_phone - collect_sms_marketing - favicon_url - fluid_shop - id - isolated_payment_tokens - kount_environment - kount_client_id - logo_url - name - order_on_behalf - primary_domain_hostname - require_billing_zip - require_phone - reward_points_apply_to_subtotal - reward_points_enabled - reward_points_label_singular - reward_points_label_plural - subdomain additionalProperties: false CheckoutCartRecurringItem: description: >- Cart recurring-charge disclosure entry produced by CartRecurringPresenter (one per subscription plan). type: object additionalProperties: false properties: subtotal: type: number subtotal_in_currency: type: - string - 'null' interval: type: - integer - 'null' interval_unit: type: - string - 'null' interval_unit_identifier: type: - string - 'null' subtotal_for_display: type: - string - 'null' start_date: type: - string - 'null' CheckoutEnrollmentPack: description: >- Cart enrollment pack rendered by EnrollmentPackBlueprinter (:cart view). Nullable when the cart has no enrollment pack. type: - object - 'null' additionalProperties: false properties: enrollment_pack_id: type: integer slug: type: - string - 'null' token: type: - string - 'null' title: type: - string - 'null' description: type: - string - 'null' enrollment_fee: type: - number - string - 'null' additional_volume: type: - integer - number - 'null' canonical_url: type: - string - 'null' enrollment_fee_in_currency: type: - string - 'null' price: type: - string - 'null' price_in_currency: type: - string - 'null' subscription_price: type: - string - 'null' subscription_price_in_currency: type: - string - 'null' images: type: array items: $ref: '#/components/schemas/CheckoutEnrollmentPackImage' items: type: array description: Enrollment pack cart items (CartItemBlueprinter :enroll_items). items: $ref: '#/components/schemas/CheckoutEnrollmentPackItem' 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' CheckoutMeta: type: object additionalProperties: false required: - request_id - timestamp properties: request_id: type: - string - 'null' timestamp: type: string format: date-time CheckoutCartItemError: description: >- Per-line checkout error entry (CartItem#item_checkout_errors). A map of error key (product, country, quantity, customer_limit, subscription_max_qty, bundle_customer_limit, bundle_subscription_max_qty) to an array of localized messages. type: object additionalProperties: type: array items: type: string CheckoutCartItemSubscriptionPlan: description: >- Subscription plan rendered by SubscriptionPlanBlueprinter (:cart_item view). type: object additionalProperties: false properties: id: type: integer name: type: - string - 'null' billing_interval: type: - integer - 'null' billing_interval_unit: type: - string - 'null' description: Localized interval unit label. billing_interval_unit_identifier: type: - string - 'null' description: Raw interval unit (day, week, month, year). billing_frequency_in_words: type: - string - 'null' shipping_interval: type: - integer - 'null' shipping_interval_unit: type: - string - 'null' volume_interval: type: - integer - 'null' volume_interval_unit: type: - string - 'null' trial_period: type: - integer - 'null' trial_period_unit: type: - string - 'null' split_volume: type: - boolean - 'null' allow_max_billing_cycles: type: - boolean - 'null' max_billing_cycles: type: - integer - 'null' savings_display_mode: type: - string - 'null' savings_label: type: - string - 'null' company_default: type: - boolean - 'null' products_count: type: - integer - 'null' subscribers_count: type: - integer - 'null' price: type: - number - string - 'null' price_in_currency: type: - string - 'null' subscription_start: type: - string - 'null' format: date-time subscribe_and_save: type: - number - string - 'null' subscribe_and_save_in_currency: type: - string - 'null' subscribe_and_save_for_display: type: - string - 'null' CheckoutBundledItem: description: >- Bundle child selection stored in cart_item.metadata["bundled_items"]. Union of every writer's key set - the legacy ProductBundle path (ItemService#serialize_bundle_item) and the bundle-group path (BundleGroupPricing build_included_item_hash / build_enriched_item / propagate_source_fields). type: object additionalProperties: false properties: variant_id: type: integer product_id: type: - integer - 'null' product_title: type: - string - 'null' variant_title: type: - string - 'null' option_titles: type: array items: type: string quantity: type: integer display_to_customer: type: - boolean - 'null' product_bundle_group_id: type: - integer - 'null' group_title: type: - string - 'null' price: type: - number - string - 'null' subscription: type: - boolean - 'null' subscription_plan_id: type: - integer - 'null' CheckoutProduct: description: >- Cart item product rendered by ProductBlueprinter (:cart view). Null for orphaned line items. type: - object - 'null' additionalProperties: false properties: id: type: integer title: type: - string - 'null' image_url: type: - string - 'null' image_path: type: - string - 'null' cv: type: - string - 'null' format: decimal tax: type: - number - string - 'null' sku: type: - string - 'null' external_id: type: - string - 'null' canonical_url: type: - string - 'null' introduction: type: - string - 'null' price: type: - number - string - 'null' price_in_currency: type: - string - 'null' tax_in_currency: type: - string - 'null' subscription_price: type: - number - string - 'null' metadata: type: - object - 'null' additionalProperties: true metafields: type: array description: Metafields rendered by LegacyMetafieldBlueprint (:with_definition). items: $ref: '#/components/schemas/CheckoutProductMetafield' metafields_collection: type: array description: Product metafields_collection entries (key/value slices). items: $ref: '#/components/schemas/CheckoutEmbeddedMetafield' product_bundle_groups: type: array description: >- Present only for bundle products (ProductBlueprinter renders this association when product.bundle?). Empty/absent for regular products. items: $ref: '#/components/schemas/CheckoutProductBundleGroup' CheckoutVariant: description: >- Cart item variant rendered by VariantBlueprinter (:physical_details view = base fields + physical dimensions). Null for orphaned line items. 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 - 'null' currency_code: type: - string - 'null' options: type: array items: $ref: '#/components/schemas/CheckoutVariantOption' 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' CheckoutEnrollmentPackImage: description: Enrollment pack image (Image#as_json - full column dump). type: object additionalProperties: false properties: id: type: integer external_id: type: - string - 'null' image_path: type: - string - 'null' image_url: type: - string - 'null' image_url_i18n: type: object description: Map of locale -> localized image URL. additionalProperties: type: - string - 'null' position: type: - integer - 'null' relateable_id: type: integer relateable_type: type: string uuid_v7: type: string created_at: type: - string - 'null' format: date-time updated_at: type: - string - 'null' format: date-time CheckoutEnrollmentPackItem: description: >- Enrollment pack cart item rendered by Commerce::CartItemBlueprinter (:enroll_items view - base fields + product_title, minus product/variant/ discount/image fields). type: object additionalProperties: false properties: id: type: integer title: type: - string - 'null' quantity: type: integer price: type: - number - string - 'null' tax: type: - number - string - 'null' cv: type: - string - 'null' format: decimal qv: type: - string - 'null' format: decimal cv_total: type: - string - 'null' format: decimal qv_total: type: - string - 'null' format: decimal cv_in_currency: type: - string - 'null' qv_in_currency: type: - string - 'null' total: type: - number - string - 'null' total_after_discounts: type: - number - string - 'null' enrollment_pack_id: type: - integer - 'null' subscription: type: - boolean - 'null' display_to_customer: type: - boolean - 'null' price_in_currency: type: - string - 'null' tax_in_currency: type: - string - 'null' total_in_currency: type: - string - 'null' total_after_discounts_in_currency: type: - string - 'null' line_total_in_currency: type: - string - 'null' line_total_after_discounts_in_currency: type: - string - 'null' unit_price_display_authoritative: type: - boolean - 'null' allow_subscription: type: - boolean - 'null' enrollment: type: - boolean - 'null' creditable_points: type: - integer - 'null' product_title: type: - string - 'null' subscription_plan_id: type: - integer - 'null' subscription_only: type: - boolean - 'null' subscription_interval: type: - integer - string - 'null' subscription_interval_unit: type: - string - 'null' subscription_interval_unit_identifier: type: - string - 'null' subscription_price: type: - number - string - 'null' subscription_price_in_currency: type: - string - 'null' subscription_start: type: - string - 'null' subscribe_and_save: type: - number - string - 'null' subscribe_and_save_in_currency: type: - string - 'null' subscribe_and_save_for_display: type: - string - 'null' metadata: type: - object - 'null' additionalProperties: true errors: type: array items: $ref: '#/components/schemas/CheckoutCartItemError' subscription_plans: type: array items: $ref: '#/components/schemas/CheckoutCartItemSubscriptionPlan' ErrorValue: description: A validation or API error value. anyOf: - type: string - type: array items: type: string - type: object additionalProperties: $ref: '#/components/schemas/JsonValue' CheckoutProductMetafield: description: >- Product metafield rendered by LegacyMetafieldBlueprint (:with_definition view). type: object additionalProperties: false properties: id: type: integer namespace: type: - string - 'null' key: type: - string - 'null' value: $ref: '#/components/schemas/JsonValue' value_type: type: - string - 'null' description: type: - string - 'null' owner_type: type: - string - 'null' owner_id: type: - integer - 'null' created_at: type: - string - 'null' format: date-time updated_at: type: - string - 'null' format: date-time metafield_definition: $ref: '#/components/schemas/CheckoutMetafieldDefinition' CheckoutEmbeddedMetafield: description: >- Embedded metafields_collection entry (key/value slice rendered by ProductBlueprinter#metafields_collection). type: object additionalProperties: false properties: key: type: - string - 'null' value: $ref: '#/components/schemas/JsonValue' CheckoutProductBundleGroup: description: >- Product bundle group rendered by ProductBundleGroupBlueprinter. Present on bundle products only. type: object additionalProperties: false properties: id: type: integer title: type: - string - 'null' description: type: - string - 'null' group_type: type: - string - 'null' purpose: type: - string - 'null' min_selections: type: - integer - 'null' max_selections: type: - integer - 'null' selection_type: type: - string - 'null' pricing_config: type: - object - 'null' additionalProperties: true properties: pricing_type: type: - string - 'null' fixed_price: type: - number - string - 'null' min_price: type: - number - string - 'null' hidden: type: - boolean - 'null' country_pricing: type: array items: type: object additionalProperties: true properties: country_code: type: - string - 'null' enabled: type: - boolean - 'null' price: type: - string - number - 'null' wholesale: type: - string - number - 'null' subscription_price: type: - string - number - 'null' wholesale_subscription_price: type: - string - number - 'null' points: type: - string - number - 'null' cv: type: - number - string - 'null' qv: type: - number - string - 'null' wholesale_cv: type: - number - string - 'null' wholesale_qv: type: - number - string - 'null' allow_subscriptions: type: - boolean - 'null' force_subscriptions: type: - boolean - 'null' sort_order: type: - integer - 'null' created_at: type: - string - 'null' format: date-time updated_at: type: - string - 'null' format: date-time images: type: array items: $ref: '#/components/schemas/CheckoutProductBundleGroupImage' bundle_group_items: type: array items: $ref: '#/components/schemas/CheckoutBundleGroupItem' CheckoutVariantOption: description: Variant option pair rendered by VariantBlueprinter#options. type: object additionalProperties: false properties: title: type: - string - 'null' value: type: - string - 'null' CheckoutMetafieldDefinition: description: >- Metafield definition rendered by MetafieldDefinitionBlueprint (default view). Null when the metafield has no definition. type: - object - 'null' additionalProperties: false properties: id: type: integer company_id: type: - integer - 'null' namespace: type: - string - 'null' key: type: - string - 'null' name: type: - string - 'null' description: type: - string - 'null' value_type: type: - string - 'null' validation_rules: $ref: '#/components/schemas/JsonValue' owner_resource: type: - string - 'null' pinned: type: - boolean - 'null' position: type: - integer - 'null' locked: type: - boolean - 'null' list_type: type: - boolean - 'null' reference_type: type: - boolean - 'null' supported_validations: type: array items: type: string validation_description: type: - string - 'null' category_ids: type: array items: type: integer created_at: type: - string - 'null' format: date-time updated_at: type: - string - 'null' format: date-time CheckoutProductBundleGroupImage: description: Bundle group image rendered by ProductImageBlueprint (:with_dam view). type: object additionalProperties: false properties: id: type: integer image_url: type: - string - 'null' image_path: type: - string - 'null' position: type: - integer - 'null' dam_asset_code: type: - string - 'null' CheckoutBundleGroupItem: description: Bundle group item rendered by BundleGroupItemBlueprinter. type: object additionalProperties: false properties: id: type: integer quantity: type: - integer - 'null' sort_order: type: - integer - 'null' config: $ref: '#/components/schemas/CheckoutBundleGroupItemConfig' variant: $ref: '#/components/schemas/CheckoutBundleGroupItemVariant' CheckoutBundleGroupItemConfig: description: >- Resolved per-item pricing/config blob rendered by BundleGroupItemBlueprinter#config. type: object additionalProperties: false properties: price: type: - number - string - 'null' pc_price: type: - number - string - 'null' resolved_price: type: - string - 'null' resolved_wholesale_price: type: - string - 'null' resolved_cv: type: - string - 'null' format: decimal resolved_qv: type: - string - 'null' format: decimal resolved_wholesale_cv: type: - string - 'null' format: decimal resolved_wholesale_qv: type: - string - 'null' format: decimal cv: type: - string - 'null' format: decimal qv: type: - string - 'null' format: decimal pc_cv: type: - string - 'null' format: decimal pc_qv: type: - string - 'null' format: decimal is_default: type: boolean quantity: type: - integer - 'null' max_quantity: type: - integer - 'null' allow_subscription: type: boolean force_subscription: type: boolean has_subscription_plans: type: boolean subscription_plans: type: array items: $ref: '#/components/schemas/CheckoutVariantSubscriptionPricing' image_url: type: - string - 'null' available_country_codes: type: array items: type: string country_prices: type: object description: Map of ISO country code -> configured price. additionalProperties: type: - number - string - 'null' CheckoutBundleGroupItemVariant: description: >- Variant on a bundle group item rendered by VariantBlueprinter (:with_product_shallow view). 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 - 'null' currency_code: type: - string - 'null' customer_limit: type: - integer - 'null' active_variant_countries: type: array items: type: string options: type: array items: $ref: '#/components/schemas/CheckoutVariantOption' product: $ref: '#/components/schemas/CheckoutBundleItemProduct' CheckoutVariantSubscriptionPricing: description: >- Per-plan subscription pricing entry rendered by V2::VariantBlueprinter.build_subscription_plans. type: object additionalProperties: false properties: id: type: integer subscription_price_in_currency: type: - string - 'null' subscribe_and_save_in_currency: type: - string - 'null' subscribe_and_save_for_display: type: - string - 'null' wholesale_subscription_price_in_currency: type: - string - 'null' wholesale_subscribe_and_save_in_currency: type: - string - 'null' wholesale_subscribe_and_save_for_display: type: - string - 'null' CheckoutBundleItemProduct: description: >- Product nested under a bundle-group-item variant, rendered by ProductBlueprinter (:item_without_bundle_groups view). type: - object - 'null' additionalProperties: false properties: id: type: integer title: type: - string - 'null' image_url: type: - string - 'null' image_path: type: - string - 'null' cv: type: - string - 'null' format: decimal cv_in_currency: type: - string - 'null' tax: type: - number - string - 'null' tax_in_currency: type: - string - 'null' sku: type: - string - 'null' external_id: type: - string - 'null' canonical_url: type: - string - 'null' introduction: type: - string - 'null' price: type: - number - string - 'null' price_in_currency: type: - string - 'null' metadata: type: - object - 'null' additionalProperties: true ````