> ## 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. > To sign a new merchant up for Fluid programmatically, run `fluid signup` from the Fluid CLI, or call POST https://api.fluid.app/api/company with no credentials, as described in /api/agent-signup. Do not automate the signup form or book a demo. Before authenticated calls are possible, the merchant must sign the agent in to the Fluid CLI with the emailed code and --shop set to the company's fluid_shop (which also confirms the signup), or open the emailed confirmation link and give the agent an API token. > After signup, to launch a merchant's store (back-office sync, payments onboarding, store setup, a theme copied from their current site, and a preview link before billing), follow /api/agent-launch. > Lists use cursor pagination via the page[cursor] and page[limit] query params; follow meta.pagination.next_cursor until it is null. > When the same operation exists on more than one surface, use the newest: dated API versions are newer than unversioned ones, and later dates win (v2026-04 > v2025-06 > unversioned v0/v1.1). Fall back to a legacy or unversioned operation only when no newer versioned equivalent exists — the company-v0 notes below list the known superseded operations. The same applies to /api/company/v1 and /api/v1/... paths: prefer a newer documented equivalent, and use one only when none exists (/api/v1.1/... is distinct and documented in company-v0). Use page/per_page offset pagination only on an operation whose spec documents those params — mostly the unversioned company-v0 admin surface, plus some lists on other surfaces, versioned ones included; page every other list with cursors. > Fluid has three navigation APIs; don't mix them up. Storefront website menus (navigation bars, footers) are /api/menus and nested menu_items, in api-reference/content-v0.yaml (API Reference: Website > Navigation menus), with a how-to in themes/navigation-menus; their list uses flat page/per_page pagination. The Fluid mobile app's navigation is /api/v2/mobile_navigations, in api-reference/mobile-v2.yaml (API Reference: Mobile app > Navigation); its list also uses page/per_page. Portal navigations belong to a portal definition (Fluid OS), in api-reference/fluid-os-v0.yaml (API Reference: Portal > Portal navigation), and each has a platform of web or mobile. > 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/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); api-reference/company-v0.yaml covers the legacy unversioned company admin surface (/api/... paths, bearer-authenticated except two operations that take no credential, POST /api/company (create a company) and GET /api/agreements/{id} — company settings and management, customers, users, roles, subscription plans, subscription bundles, subscriptions, media, pages, catch-ups, inventory levels, domains, agreements, and admin order actions). company-v0 caveats: it is the legacy v0 admin contract and its lists use flat page/per_page offset pagination, which is expected there despite the general cursor-pagination rule; where an operation exists in both company-v0 and a versioned spec, prefer the versioned spec — the subscriptions lifecycle (list/create/show/update, cancel, pause, reactivate, resume, retry, skip, failed-cycle-waiver, discounts) and subscription bundles are superseded by checkout-v2026-04, and company pages/media CRUD plus the public pages, categories, products, and media list endpoints are superseded by storefront-v2026-04. Subscription plan management (/api/subscription_plans, resource-wrapped {"subscription_plan": {...}} bodies) exists only in company-v0. api-reference/members-v2025-06.yaml covers the v2025-06 unified Member identity surface (/api/v2025-06/members/... paths, bearer-authenticated — member list/create/show/update, lookup by email/username/external_id/legacy_customer_id, member-type assignment, and the sponsor genealogy read). Prefer it over the customers and reps surfaces when the member type matters: /customers does not serialize member_type. api-reference/analytics-v2026-04.yaml covers the v2026-04 Home dashboard analytics surface (/api/v202604/analytics/dashboard/... paths, bearer-authenticated — read-only endpoints for the Home > Overview, Home > Live, and Home > Field tabs, each accepting an optional country ISO alpha-2 query param that scopes aggregations to a single country). > api-reference/analytics-v0.yaml covers the unversioned analytics surface that backs the fluid-admin Traffic tab (/api/analytics/... and /api/analytics/traffic/... paths, bearer-authenticated — the legacy shares/views/visitors summary plus traffic overview, ranked campaigns, sources, geographies, flows, and per-rep breakdown, all sharing one reporting-period contract). > Successful responses wrap the resource payload alongside a top-level integer status and a meta object. > Portal Definition authoring edits and synchronizes the portal JSON resource graph. Widget Package authoring builds either a company-owned or Droplet-owned Remote DOM package. These are separate contracts; do not imply that one defines the other. > For Widget Package worker code, use only @fluid-app/portal-sdk/widgets/worker. Use only the Portal Definition and Widget Package workflows and public entry points documented here; do not infer support for undocumented surfaces. > Every portal function and declarative capability used by a widget must appear in that widget's uses array. Use the same typed function value in uses; do not invent capability-name strings. > Widget styling must use the portal's semantic theme variables for colors, typography, spacing, radii, borders, focus, and charts whenever a token represents the visual decision. Do not create a separate light or dark palette or duplicate theme controls as widget properties. > Prefer worker-safe Fluid UI components exported by @fluid-app/portal-sdk/widgets/worker when they fit the interaction. When no exported component fits, use semantic HTML, accessible behavior, and the portal theme variables. > A Portal Definition push updates the remote working definition. A portal version is an immutable snapshot, and activation is a separate live release operation. > The Help Center (/help/...) is for merchants, admins and reps using Fluid. Its admin pages mirror the admin's routes: the screen at admin.fluid.app/settings/taxes is documented at /help/admin/settings/taxes. Use the Help Center for how-to questions about the admin, and the Developer Platform and API Reference for building integrations. > Help Center pages describe what a company admin sees. A reader's role can hide screens and actions; admins manage roles on Settings > Roles (/help/admin/settings/roles). If someone can't find a screen or button, their role's permissions are the first thing to check. > Send people who need Fluid support to /help/getting-help. Don't invent support email addresses, phone numbers or response times. # Update a cart item (PUT) > The PUT form of `PATCH /api/checkout/v2026-04/carts/{cart_token}/items/{id}`. Both methods reach one update action, take the same body and return the same responses. Read that operation for the details. ## OpenAPI ````yaml /api-reference/checkout-v2026-04.yaml put /api/checkout/v2026-04/carts/{cart_token}/items/{id} 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 for `carts/{cart_token}/sync`, `carts/{cart_token}/volume_rep`, and `carts/{cart_token}/discount/manual`. It is also required conditionally when `PATCH carts/{cart_token}` selects an enrollment target with `member_type_id`; profile-only PATCH requests remain public. 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`), `subscription_bundles` and `subscription-profiles`. `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. **Sandbox test companies.** A sandbox test company is linked to a live company. While the test company cannot be reached, because sandbox access is turned off for its live company or the live company was deleted: - a cart token for one of its carts answers exactly as a token no cart holds, with the operation's documented `404` (cart not found), so the response does not reveal that the cart exists; - an operation that resolves the company from a bearer credential refuses that credential with `403` and the body `{"error": ""}`, before the operation runs. These refusals are documented here once rather than on each operation. 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, checkout handoff, and logout. x-fluid-section: Checkout - name: cart-discount description: >- Apply, list, and remove promo codes (discount codes) on a cart, including admin manual discounts. - name: cart-items description: Add, update, and remove line items on a cart. x-fluid-section: Checkout - name: cart-sms-consent description: >- The disclosure for recurring subscription texts and the shopper's choice about them on a cart. x-fluid-section: Checkout - 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. x-fluid-section: Checkout - name: subscriptions description: >- Manage subscriptions — pause, resume, skip, cancel, reactivate, retry, and failed-cycle waivers. x-fluid-section: Checkout - name: subscription-manage-link description: >- The subscriptions a manage link reaches. The bearer is the link's scoped token (`sml_...`, from the `manage_url` of the subscription_upcoming_renewal webhook), not a session. It names one company, the subscriptions of one renewal order and the actions it allows, and it expires at the end of the day after the local bill date. Only these operations accept it, and they accept no other credential. The responses carry no customer data. x-fluid-section: Checkout - name: subscription-sms-consent description: >- The recurring subscription texts choice for a customer's subscription, and the disclosure shown next to it. x-fluid-section: Checkout - name: subscription-bundles description: List and create subscription bundles. - name: subscription-profiles description: Change an autoship profile as a whole. Requires Subscription Pro. x-fluid-section: Checkout paths: /api/checkout/v2026-04/carts/{cart_token}/items/{id}: put: tags: - cart-items summary: Update a cart item (PUT) description: >- The PUT form of `PATCH /api/checkout/v2026-04/carts/{cart_token}/items/{id}`. Both methods reach one update action, take the same body and return the same responses. Read that operation for the details. operationId: checkout_v2026_04_update_cart_item_put parameters: - name: cart_token in: path required: true description: Cart token schema: type: string - name: id in: path required: true description: Cart item ID schema: type: integer requestBody: $ref: '#/components/requestBodies/UpdateCartItem' responses: '200': $ref: '#/components/responses/CartUpdated' '404': $ref: '#/components/responses/CartNotFound' '409': $ref: '#/components/responses/PaymentInProgressError' '410': $ref: '#/components/responses/ProcessedCartResponse' '422': $ref: '#/components/responses/UnprocessableEntity' security: [] components: requestBodies: UpdateCartItem: content: application/json: examples: change_quantity: summary: Change a line item's quantity value: quantity: 3 schema: type: object additionalProperties: false properties: variant_id: type: integer description: New variant ID quantity: type: integer description: New quantity subscription: type: boolean description: Toggle subscription subscription_plan_id: type: integer description: Subscription plan ID responses: CartUpdated: description: Success content: application/json: schema: $ref: '#/components/schemas/CartResponse' example: cart: id: 482913 cart_token: ct_4mK8vQ2nR7xT9pL3wY6zBd state: start state_revision: 5 population_status: complete type: regular enrollment: false email: holly.flax@dundermifflin.com phone: '+15705550142' language_iso: en currency_code: USD currency_symbol: $ currency_decimal_places: 2 customer_id: 58201 buyer_rep_id: 3017 enrollment_pack_id: null enrollment_member_type: null processed: false email_marketing: true sms_marketing: false auto_apply_points: false cv_total: '40.0' qv_total: '40.0' amount_total: 126.77 sub_total: 109.98 tax_total: 8.8 shipping_total: 7.99 discount_total: 0 subtotal_after_discounts: 109.98 transaction_fee: 0 enrollment_fee: 0 inclusive_shipping_tax: 0 shipping_discount: 0 remaining_cart_amount_after_points: 126.77 amount_total_in_currency: $126.77 sub_total_in_currency: $109.98 tax_total_in_currency: $8.80 shipping_total_in_currency: $7.99 discount_total_in_currency: $0.00 subtotal_after_discounts_in_currency: $109.98 transaction_fee_in_currency: $0.00 enrollment_fee_in_currency: $0.00 customer_total_points_in_currency: $12.50 points_applied_amount_in_currency: $0.00 remaining_customer_points_amount_in_currency: $12.50 remaining_cart_amount_after_points_in_currency: $126.77 tax_total_for_display: $8.80 shipping_total_for_display: $7.99 tax_exempt: false digital_only: false immutable_items: false points_enabled: true price_inclusive_of_tax: false requires_3ds: false requires_payment_method: true vault_without_charge: false valid_for_checkout: false valid_for_checkout_pre_payment: true checkout_blockers: [] contains_subscription: false payment_method_auto_assignable: false payment_unavailable_reason: null customer_total_points: 1250 customer_total_points_decimal: '1250.0000' points_applied: 0 points_applied_decimal: '0.0000' remaining_customer_points: 1250 remaining_customer_points_decimal: '1250.0000' max_applicable_points: 1250 points_unavailable_in_market: false max_applicable_points_decimal: '1250.0000' total_creditable_points: 110 total_creditable_points_decimal: '110.0000' totals: gross_subtotal: '109.98' gross_subtotal_in_currency: $109.98 net_subtotal: '109.98' net_subtotal_in_currency: $109.98 item_tax: '8.80' item_tax_in_currency: $8.80 shipping_net: '7.99' shipping_net_in_currency: $7.99 shipping_tax: '0.00' shipping_tax_in_currency: $0.00 total_tax: '8.80' total_tax_in_currency: $8.80 price_inclusive_of_tax: false tax_label: null price_inclusive_tax_name: null payment_account: null discount_codes: [] product_discount_codes: [] shipping_discount_codes: [] buyer_rep: id: 3017 email: dwight.schrute@dundermifflin.com full_name: Dwight Schrute image_url: >- https://cdn.fluid.app/companies/1405/members/dwight-schrute.jpg external_id: DM-REP-0042 buyer_rep_member_id: 8d2f6b1a-4c3e-4f7a-9b15-2e6c0a9d7f41 volume_rep: null volume_rep_member_id: null shipping_method: id: '61842' name: Standard Ground discount_breakdown: internal_discounts: 0 external_discounts: 0 total_discounts: 0 available_shipping_methods: - id: '61842' title: Standard Ground price: 7.99 delivery_time_estimate: 3-5 business days price_label: $7.99 - id: '61843' title: Two-Day Express price: 19.99 delivery_time_estimate: 1-2 business days price_label: $19.99 metadata: {} messages: {} payment_method: null available_payment_methods: - id: 3308 uuid: pa_7Hq2Wd9LmR4xVb6NcTe3Kp type: credit_card name: Credit Card image_url: https://cdn.fluid.app/payment_icons/generic.svg test: false sandbox: false supported_brands: - visa - mastercard - amex - discover token_provider: vgs bogus_gateway: false apple_pay: false apple_pay_recurring_supported: false apple_pay_merchant_identifier: null customer_details_schema: {} collect_billing_address: true external_discount: total: 0 calculated_at: null sources: {} shipping_address: name: Holly Flax address1: 1725 Slough Avenue address2: Suite 200 address3: null city: Scranton state: PA postal_code: '18505' country_code: US subdivision_code: US-PA phone: '+15705550142' billing_address: name: Holly Flax address1: 1725 Slough Avenue address2: Suite 200 address3: null city: Scranton state: PA postal_code: '18505' country_code: US subdivision_code: US-PA phone: '+15705550142' items: - id: 731284 allow_subscription: true bundled_items: [] creditable_points: 55 cv: '20.0' cv_total: '40.0' discount_amount: '0.0' discount_amount_in_currency: $0.00 display_to_customer: true enrollment: false enrollment_pack_id: null errors: [] free_item: false image_url: >- https://cdn.fluid.app/companies/1405/products/20lb-copy-paper.jpg line_total_after_discounts_in_currency: $109.98 line_total_in_currency: $109.98 metadata: {} price: '54.99' price_in_currency: $54.99 price_unavailable: false product: id: 48213 canonical_url: https://shop.dundermifflin.com/products/20lb-copy-paper cv: '20' external_id: null image_path: companies/1405/products/20lb-copy-paper.jpg image_url: >- https://cdn.fluid.app/companies/1405/products/20lb-copy-paper.jpg introduction: >- Ten reams of bright white 20lb multipurpose paper per case. metadata: {} metafields: [] metafields_collection: [] price: '54.99' price_in_currency: $54.99 sku: DM-20LB-CASE subscription_price: '49.49' tax: '0.0' tax_in_currency: $0.00 title: Dunder Mifflin 20lb Copy Paper product_title: Dunder Mifflin 20lb Copy Paper quantity: 2 qv: '20.0' qv_total: '40.0' regular_line_total_in_currency: $109.98 subscribe_and_save: null subscribe_and_save_for_display: null subscribe_and_save_in_currency: null subscription: false subscription_interval: null subscription_interval_unit: null subscription_interval_unit_identifier: null subscription_only: false subscription_plan_id: null subscription_plans: [] subscription_price: '49.49' subscription_price_in_currency: $49.49 subscription_start: null tax: '0.0' tax_in_currency: $0.00 title: Dunder Mifflin 20lb Copy Paper total: '109.98' total_after_discounts: '109.98' total_after_discounts_in_currency: $109.98 total_in_currency: $109.98 unit_price_display_authoritative: true variant: id: 90731 currency_code: USD display_name: Dunder Mifflin 20lb Copy Paper - Case of 10 reams height: 11 hs_code: '4802.56' image_path: companies/1405/products/20lb-copy-paper.jpg image_url: >- https://cdn.fluid.app/companies/1405/products/20lb-copy-paper.jpg length: 17.5 options: - title: Pack size value: Case of 10 reams physical: true price: '54.99' price_in_currency: $54.99 primary_image: >- https://cdn.fluid.app/companies/1405/products/20lb-copy-paper.jpg sku: DM-20LB-CASE title: Case of 10 reams unit_of_size: in unit_of_weight: lb weight: '50.0' width: 11.5 ship_to: id: 1054268 address1: 1725 Slough Avenue address2: Suite 200 address3: null city: Scranton country_code: US country_num_code: 840 default: true name: Holly Flax phone: '+15705550142' postal_code: '18505' state: PA subdivision_code: US-PA bill_to: id: 1054268 address1: 1725 Slough Avenue address2: Suite 200 address3: null city: Scranton country_code: US country_num_code: 840 default: true name: Holly Flax phone: '+15705550142' postal_code: '18505' state: PA subdivision_code: US-PA attribution: id: 91877 username: dwight-schrute agreements: - id: 5521 default_checked: false enrollment_pack_id: null required: true show_at_checkout: true show_path: /api/agreements/5521 standalone_on_checkout: false content_digest: >- 4f7f9a2d0c6b1e8e3a5d9c7b2f1e0d4c8b6a5f3e2d1c0b9a8f7e6d5c4b3a2918 subscription_only: false title: Dunder Mifflin Terms of Sale country: id: 233 currency_code: USD currency_symbol: $ iso: US iso3: USA iso_name: UNITED STATES name: United States price_inclusive_of_tax: false price_inclusive_tax_name: '' province_required: true tax_enabled: true tax_standard_rate: null company: id: 1405 bundle_subscriptions: false checkout_primary_button_color: '#1F4E79' checkout_primary_text_color: '#FFFFFF' checkout_secondary_button_color: '#E7EEF5' checkout_secondary_text_color: '#1F4E79' collect_email_marketing: true collect_phone: true collect_sms_marketing: false favicon_url: https://cdn.fluid.app/companies/1405/favicon.png fluid_shop: dunder-mifflin.fluid.app hide_volume_on_customer_surfaces: false isolated_payment_tokens: false kount_client_id: null kount_environment: production logo_url: https://cdn.fluid.app/companies/1405/logo.png name: Dunder Mifflin Paper Company order_on_behalf: true primary_domain_hostname: shop.dundermifflin.com require_billing_zip: true require_phone: false reward_points_apply_to_subtotal: true reward_points_enabled: true reward_points_label_plural: Schrute Bucks reward_points_label_singular: Schrute Buck subdomain: dunder-mifflin recurring: [] enrollment_pack: null meta: request_id: 6f1c2a9e-3b7d-4e58-9a21-c4d8e0b7f312 timestamp: '2026-09-14T15:22:08Z' checkout_url: >- https://checkout.fluid.app/checkouts/ct_4mK8vQ2nR7xT9pL3wY6zBd?fluid_shop=dunder-mifflin shop_url: https://shop.dundermifflin.com/ CartNotFound: description: Cart not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' PaymentInProgressError: description: > A redirect payment (PPRO, dLocal, Citcon) is open at the provider, so the cart refuses writes until the charge resolves (`meta.code` = `payment_in_progress`). The provider collects the amount the charge opened with, and the order is built from this cart when it does. content: application/json: schema: $ref: '#/components/schemas/PaymentInProgressErrorResponse' 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), carries an authorized or captured charge (its prices are settled once money has moved), 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' UnprocessableEntity: description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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 required: - id - cart_token - state - state_revision - population_status - type - enrollment - email - phone - phone_dialable - language_iso - currency_code - currency_symbol - currency_decimal_places - customer_id - buyer_rep_id - enrollment_pack_id - enrollment_member_type - processed - payment_in_progress - payment_resume_url - email_marketing - sms_marketing - sms_marketing_preselected - cv_total - qv_total - amount_total - sub_total - tax_total - shipping_total - discount_total - subtotal_after_discounts - transaction_fee - enrollment_fee - inclusive_shipping_tax - shipping_discount - remaining_cart_amount_after_points - amount_total_in_currency - sub_total_in_currency - tax_total_in_currency - shipping_total_in_currency - discount_total_in_currency - subtotal_after_discounts_in_currency - transaction_fee_in_currency - enrollment_fee_in_currency - customer_total_points_in_currency - points_applied_amount_in_currency - remaining_customer_points_amount_in_currency - remaining_cart_amount_after_points_in_currency - tax_total_for_display - shipping_total_for_display - tax_exempt - digital_only - immutable_items - points_enabled - price_inclusive_of_tax - requires_3ds - requires_payment_method - vault_without_charge - valid_for_checkout - valid_for_checkout_pre_payment - checkout_blockers - contains_subscription - payment_method_auto_assignable - payment_unavailable_reason - customer_total_points - customer_total_points_decimal - points_applied - points_applied_decimal - remaining_customer_points - remaining_customer_points_decimal - max_applicable_points - points_unavailable_in_market - max_applicable_points_decimal - total_creditable_points - total_creditable_points_decimal - totals - price_inclusive_tax_name - payment_account - discount_codes - product_discount_codes - shipping_discount_codes - buyer_rep - buyer_rep_member_id - volume_rep - volume_rep_member_id - shipping_method - discount_breakdown - available_shipping_methods - metadata - messages - payment_method - available_payment_methods - external_discount - shipping_address - billing_address - items - ship_to - bill_to - attribution - agreements - country - company - recurring - enrollment_pack 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. population_status: type: string enum: - pending - complete - failed description: >- Progress of the background job that adds a deferred create's items. `pending` while it runs, then `complete` or `failed`. A synchronous create returns `complete`. An unexpected job error can leave it `pending`, so clients should stop waiting after a timeout. type: type: - string - 'null' description: >- Cart type discriminator (e.g. enrollment vs standard); `null` when unset. enrollment: type: boolean description: >- Whether the cart is flagged as enrollment eligible, with or without an enrollment pack. 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. phone_dialable: type: boolean description: >- Whether checkout keeps `phone` on the customer's profile: it must parse as a possible number with its +country code. Checkout offers SMS consent for a saved phone only when this is true. 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`. enrollment_member_type: description: >- Immutable member-type target copied from the enrollment pack, or `null` for non-enrollment and historical carts. examples: - id: 22c58158-7f6c-4f33-a033-32e259941684 slug: rep name: Representative - null anyOf: - type: object additionalProperties: false required: - id - slug - name properties: id: type: string format: uuid slug: type: string name: type: string - type: 'null' processed: type: boolean description: > `true` once the cart has been completed into an order. A processed cart is locked — further mutations return `410`. payment_in_progress: type: boolean description: > `true` while a redirect payment (PPRO, dLocal, Citcon) is open at the provider. Cart writes answer `409` with `meta.code` = `payment_in_progress` until the charge resolves. payment_resume_url: type: - string - 'null' description: > Fluid's resume endpoint for the open payment (`GET /api/checkout/v2026-04/carts/{cart_token}/payment/resume`), which redirects the shopper to the provider page; the provider link itself can carry a session credential and is never returned. The link carries a short-lived token (one hour) minted for the shopper reading the cart, and is absent from callback payloads. `null` when no payment is in progress or the provider gave no page (a BLIK mandate is approved in the banking app). 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. sms_marketing_preselected: type: boolean description: >- True only in the authenticated member's own cart sync response, when that attached member is opted in and their consent phone matches the profile-dialable cart phone. False for every unauthenticated or different-member response. auto_apply_points: type: boolean description: >- Whether renewals created from this cart apply reward points automatically cv_total: type: - string - 'null' format: decimal qv_total: type: - string - 'null' format: decimal amount_total: type: - number - 'null' description: >- Grand total the buyer pays, in the cart currency (items + tax + shipping - discounts). Null when unavailable, meaning a bundle price for this tier cannot be computed and checkout refuses the line. sub_total: type: - number - 'null' description: >- Sum of line-item prices before tax, shipping, and discounts. Null when unavailable, meaning a bundle price for this tier cannot be computed and checkout refuses the line. tax_total: type: - number - 'null' description: >- Total tax on the cart. Null when unavailable, meaning a bundle price for this tier cannot be computed and checkout refuses the line. shipping_total: type: number description: Total shipping charge for the selected method. discount_total: type: - number - 'null' description: >- Total value of all applied discounts. Null when unavailable, meaning a bundle price for this tier cannot be computed and checkout refuses the line. subtotal_after_discounts: type: - number - 'null' description: >- Item subtotal after discounts are applied, before tax and shipping. Null when unavailable, meaning a bundle price for this tier cannot be computed and checkout refuses the line. 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 - 'null' description: >- Amount still due after applying loyalty points. Null when unavailable, meaning a bundle price for this tier cannot be computed and checkout refuses the line. amount_total_in_currency: type: - string - 'null' description: >- Unavailable (null): a bundle price for this tier cannot be computed; checkout refuses the line. sub_total_in_currency: type: - string - 'null' description: >- Unavailable (null): a bundle price for this tier cannot be computed; checkout refuses the line. tax_total_in_currency: type: - string - 'null' description: >- Unavailable (null): a bundle price for this tier cannot be computed; checkout refuses the line. shipping_total_in_currency: type: string discount_total_in_currency: type: - string - 'null' description: >- Unavailable (null): a bundle price for this tier cannot be computed; checkout refuses the line. subtotal_after_discounts_in_currency: type: - string - 'null' description: >- Unavailable (null): a bundle price for this tier cannot be computed; checkout refuses the line. 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 - 'null' description: >- Unavailable (null): a bundle price for this tier cannot be computed; checkout refuses the line. tax_total_for_display: type: - string - 'null' description: >- Unavailable (null): a bundle price for this tier cannot be computed; checkout refuses the line. 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). checkout_blockers: type: array description: >- Why `valid_for_checkout_pre_payment` is false, one entry per reason. Empty when it is true. Render these instead of a generic message. items: type: object properties: code: type: string description: >- Stable identifier for the validator that blocked checkout, e.g. `shipping_address`. Key your own customer-facing copy off this. message: type: string description: >- The validator's own English wording, as a fallback for a `code` the client does not recognise. Not translated. field: type: - string - 'null' description: >- The cart API path to fix for this blocker, for example `shipping_address`, or null when no single field applies. payment: type: string enum: - not_attempted - declined - unknown - held description: >- What happened to the payment: the catalog default for the blocker's `code`, which is `not_attempted` for every blocker code; `held` instead when the cart's only money is the payment a resubmit reuses; or `unknown` on every blocker while the cart may already hold money or that cannot be read. Check before charging again on `unknown`. `declined` reflects the stored payment status; for some gateways an unconfirmed failure is still reported as `declined`. required: - code - message additionalProperties: false contains_subscription: type: boolean description: >- `true` when the cart contains a subscribed top-level item or bundle child. payment_method_auto_assignable: type: boolean description: >- `true` when a payment method can be auto-assigned without buyer input. customer_total_points: type: integer customer_total_points_decimal: type: string pattern: ^-?\d+\.\d{4}$ description: Customer points balance as an exact four-place decimal string. example: '120.0000' points_applied: type: integer points_applied_decimal: type: string pattern: ^-?\d+\.\d{4}$ description: Applied points as an exact four-place decimal string. example: '120.0000' remaining_customer_points: type: integer remaining_customer_points_decimal: type: string pattern: ^-?\d+\.\d{4}$ description: Remaining customer points as an exact four-place decimal string. example: '120.0000' max_applicable_points: type: integer points_unavailable_in_market: type: boolean description: >- True when points cannot be spent in this cart's market because nobody set its points value and the company refuses such markets. False for a cart an earlier checkout attempt already spent points on. Checkout shows the points option disabled, naming the market. max_applicable_points_decimal: type: string pattern: ^-?\d+\.\d{4}$ description: Maximum applicable points as an exact four-place decimal string. example: '120.0000' total_creditable_points: type: integer total_creditable_points_decimal: type: string pattern: ^-?\d+\.\d{4}$ description: Total creditable points as an exact four-place decimal string. example: '120.0000' totals: type: - object - 'null' 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. 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 description: >- Attributed buyer rep summary, or `null` when the cart has no buyer rep. properties: id: type: - integer - 'null' description: >- Legacy user_company id of the buyer rep. `null` for a native-only rep (which has no legacy id); use `buyer_rep_member_id` for the durable member reference. email: type: - string - 'null' full_name: type: - string - 'null' image_url: type: - string - 'null' external_id: type: - string - 'null' buyer_rep_member_id: type: - string - 'null' format: uuid description: >- Durable member UUID of the buyer rep, or `null` when the cart has no buyer rep. Populated for both legacy and native reps. volume_rep: type: - object - 'null' additionalProperties: false description: >- Attributed volume rep summary, or `null` when the cart has no volume rep. properties: id: type: - integer - 'null' description: >- Legacy user_company id of the volume rep. `null` for a native-only rep (which has no legacy id); use `volume_rep_member_id` for the durable member reference. email: type: - string - 'null' full_name: type: - string - 'null' image_url: type: - string - 'null' volume_rep_member_id: type: - string - 'null' format: uuid description: >- Durable member UUID of the volume rep, or `null` when the cart has no volume rep. Populated for both legacy and native reps. 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 required: - id - title - price - delivery_time_estimate - price_label properties: id: type: string description: Identifier of the available shipping method. title: type: - string - 'null' description: Display name of the method. price: type: number 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 description: Preformatted price label for display. metadata: type: - object - 'null' description: >- Free-form cart metadata. Platform-owned keys cannot be written or removed through the metadata endpoints. Some of them are also omitted here, so they never appear in this object even when the cart carries one: `checkout_from_admin` and `legacy_customer_id`, for example. Others are still returned, because the server sets them for clients to read: `tax_label` (the tax provider's label) and `shipping`, for example. additionalProperties: true messages: type: object additionalProperties: false properties: errors: type: array items: type: string warnings: type: array items: type: string info: type: array items: type: string payment_method: $ref: '#/components/schemas/CheckoutCartPaymentMethod' available_payment_methods: type: array items: $ref: '#/components/schemas/CheckoutAvailablePaymentMethod' payment_unavailable_reason: type: - string - 'null' description: >- Why available_payment_methods is empty, or null when payment is available. Diagnostic only; it does not change what the cart may do. enum: - no_gateway_for_country - below_minimum_amount - filtered_out - test_mode_no_gateway - test_mode_gateway_ineligible - null 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. deactivated_discount_codes: type: array items: type: string description: >- Present on the update-cart response when changing the email stopped one or more applied discount codes from applying, because the new email does not qualify for them. The codes stay on the cart and apply again if the email changes back. example: - WELCOME10 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' PaymentInProgressErrorResponse: description: | 409 envelope for a cart write refused while a redirect payment is open at the provider (CURRENT-3992). `meta.cart` is the cart as it stands, so the client can show the pending payment without a second fetch. 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 - code - shop_url - cart properties: request_id: type: - string - 'null' timestamp: type: string format: date-time code: type: string enum: - payment_in_progress shop_url: type: string cart: cf229de1-dcab-43db-9f1c-57b74d0a3eff error_details: type: array minItems: 1 description: >- Every reason this write was refused, each with a stable `code`, the cart `field` to fix, and the `payment` outcome. items: $ref: '#/components/schemas/CheckoutErrorDetail' coded_recovery: type: boolean description: >- Present and true when the company routes checkout refusals by `error_details` (CHECKOUT_CODED_REFUSALS). Temporary; removed with that flag. 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: 7e9d3f64-d313-4159-99e4-992129428e07 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 required: - id - type 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 description: > The details the shopper supplied for this payment method. The national document in `document_id` is masked: every character but the last two is replaced by `*`. A signed-in customer reads their own stored values from `GET /api/checkout/v2026-04/customers/me/payment_methods/customer_details`. 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). In a country with a national-document rule the server also names the document and carries a sample of it, so document_id arrives with a country-specific label and an additional example. type: object additionalProperties: type: object additionalProperties: false required: - label - type - required properties: label: type: string type: type: string required: type: boolean example: description: >- A document the provider accepted, for placeholder text. Present only on document_id, and only in a country Commerce::Payments::NationalDocument has a rule for. type: string 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' google_pay: type: boolean description: Whether the checkout can offer Google Pay on this card account. google_pay_merchant_id: type: - string - 'null' description: >- The merchant's Google Pay merchant ID, for the PaymentDataRequest's merchantInfo. Present only when google_pay is true. google_pay_gateway: type: - string - 'null' description: >- The tokenization gateway for PAYMENT_GATEWAY tokenization (verygoodsecurity). Present only when google_pay is true. google_pay_gateway_merchant_id: type: - string - 'null' description: >- The gatewayMerchantId VGS issued the merchant. Present only when google_pay is true. client_id: type: - string - 'null' merchant_id: type: - string - 'null' sdk_type: type: - string - 'null' decrypted_apple_pay_via_paypal: type: boolean environment: type: string enum: - production - sandbox description: | Which PayPal the client_id belongs to. PayPal only. The v6 browser SDK requires it and no longer infers it. 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 required: - id - title - quantity - price - discount_amount - tax - cv - qv - cv_total - qv_total - total - total_after_discounts - enrollment_pack_id - subscription - display_to_customer - image_url - price_in_currency - tax_in_currency - discount_amount_in_currency - total_in_currency - total_after_discounts_in_currency - line_total_in_currency - line_total_after_discounts_in_currency - regular_line_total_in_currency - unit_price_display_authoritative - price_unavailable - free_item - allow_subscription - enrollment - creditable_points - product_title - subscription_plan_id - subscription_only - subscription_interval - subscription_interval_unit - subscription_interval_unit_identifier - subscription_price - subscription_price_in_currency - subscription_start - subscribe_and_save - subscribe_and_save_in_currency - subscribe_and_save_for_display - metadata - errors - subscription_plans - bundled_items - product - variant 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. Null when unavailable, meaning a bundle price for this tier cannot be computed and checkout refuses the line. discount_amount: type: - number - string - 'null' description: >- Discount applied to this line. Null when unavailable, meaning a bundle price for this tier cannot be computed and checkout refuses the line. tax: type: - number - string - 'null' description: >- Tax attributable to this line. Null when unavailable, meaning a bundle price for this tier cannot be computed and checkout refuses the 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). Null when unavailable, meaning a bundle price for this tier cannot be computed and checkout refuses the line. total_after_discounts: type: - number - string - 'null' description: >- Line total after this line's discounts are applied. Null when unavailable, meaning a bundle price for this tier cannot be computed and checkout refuses the line. 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. Null when unavailable, meaning a bundle price for this tier cannot be computed and checkout refuses the line. tax_in_currency: type: - string - 'null' description: >- Currency-formatted line tax for display. Null when unavailable, meaning a bundle price for this tier cannot be computed and checkout refuses the line. 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' regular_line_total_in_currency: type: - string - 'null' description: >- One-time/regular price total (unit regular price times quantity), independent of the item's current subscription state — unlike line_total_in_currency, which tracks whatever price is currently on the item. unit_price_display_authoritative: type: - boolean - 'null' price_unavailable: type: boolean description: >- `true` when a bundle price for this tier cannot be computed: the line's price fields are null and checkout refuses it (Plan D bundle tier pricing). `false` for every other line. subscription_start_notice: description: >- The blackout rule's checkout message when it moved subscription_start off a blocked day, otherwise null. Informational only; checkout never refuses on it. A client treats a missing field as null. anyOf: - $ref: '#/components/schemas/CheckoutCartSubscriptionStartNotice' - type: '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). Ordered: the plan the line is offered first (the line's own plan, else the product's own default), then the product's other plans in the order they were linked. A client that preselects a plan reads the first entry. Each entry's `default` marks the product's own default plan. 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 - 'null' description: >- Primary street line of the address; `null` for a wallet-partial address. address2: type: - string - 'null' description: Second address line; nullable string column (AddressBlueprinter). address3: type: - string - 'null' description: Third address line; nullable string column (AddressBlueprinter). city: type: - string - 'null' description: City / locality; `null` when unset. country_code: type: - string - 'null' description: ISO 3166-1 alpha-2 country code (e.g. `US`); `null` when unset. country_num_code: type: - integer - 'null' description: >- ISO 3166-1 numeric country code; `null` when the address has no country. 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 - 'null' description: Postal / ZIP code; `null` when the address has none. state: type: - string - 'null' description: State / province / region; `null` when unset. subdivision_code: type: - string - 'null' description: ISO subdivision code; nullable string column (AddressBlueprinter). 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 required: - id - title - show_at_checkout - default_checked - subscription_only - standalone_on_checkout - show_path - enrollment_pack_id - required - content_digest properties: id: type: integer title: type: - string - 'null' show_at_checkout: type: boolean default_checked: type: boolean subscription_only: type: boolean standalone_on_checkout: type: boolean show_path: type: string 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). content_digest: type: string pattern: ^[0-9a-f]{64}$ description: | SHA-256 hex digest of the agreement text as rendered for this cart, naming the version the shopper is shown. Send it back in `accepted_agreement_versions` when completing the cart so the checkout can refuse, before any charge, a consent to wording the merchant has changed since. 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: uuid: type: string format: uuid description: >- The company's uuid_v7, which the identity service names it by (its `org`). identity_sign_in_enabled: type: boolean description: >- Whether the company's shoppers sign in through the identity service rather than the legacy code. Read through the company's sign-in path, never set here. checkout_identity_enabled: type: boolean description: >- Whether checkout is identity-only for the company; true only when it signs in through the identity service and its release flag is on. 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 sms_terms_url: type: - string - 'null' format: uri description: >- The merchant's SMS terms override, or its storefront /terms-conditions page by default. Null when the company does not collect SMS marketing or when no HTTPS policy URL is available. sms_privacy_policy_url: type: - string - 'null' format: uri description: >- The merchant's SMS privacy policy override, or its storefront /privacy-policy page by default. Null when the company does not collect SMS marketing or when no HTTPS policy URL is available. favicon_url: type: - string - 'null' fluid_shop: type: string hide_volume_on_customer_surfaces: type: boolean 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 - hide_volume_on_customer_surfaces - 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 required: - subtotal - subtotal_in_currency - interval - interval_unit - interval_unit_identifier - subtotal_for_display - start_date properties: subtotal: type: - number - 'null' 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' subscription_start_notice: description: >- The blackout rule's checkout message when it moved this plan's first bill date (start_date) off a blocked day, otherwise null. Informational only. A client treats a missing field as null. anyOf: - $ref: '#/components/schemas/CheckoutCartSubscriptionStartNotice' - type: 'null' CheckoutEnrollmentPack: description: >- Cart enrollment pack rendered by EnrollmentPackBlueprinter (:cart view). Nullable when the cart has no enrollment pack. type: - object - 'null' additionalProperties: false required: - enrollment_pack_id - slug - token - title - description - enrollment_fee - additional_volume - canonical_url - enrollment_fee_in_currency - price - price_in_currency - subscription_price - subscription_price_in_currency - images - items 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 code: type: string description: >- Machine code for the refusal, for example `payment_unconfirmed`, or `next_bill_date_blackout` when a merchant caller (an admin credential) picks a bill date on a blackout day. A shopper is never refused for a blackout day. Their date is saved on the next open day and the success response carries the saved date. blocked_date: type: string format: date description: >- Present with `next_bill_date_blackout`. The date that was refused, as an ISO 8601 calendar date. example: '2026-11-30' blocked_day: type: integer minimum: 1 maximum: 31 description: >- Present with `next_bill_date_blackout`. The day of the month of `blocked_date`. example: 30 allowed_date: type: string format: date description: >- Present with `next_bill_date_blackout`. The nearest date the merchant's blackout rules allow, the date to offer instead. example: '2026-11-28' payment_uuid: type: string description: >- Present with `payment_unconfirmed`. The payment to look up before charging again. error_details: type: array minItems: 1 description: >- Every reason this checkout was refused, each with a stable `code`, the cart `field` to fix, and the `payment` outcome. items: $ref: '#/components/schemas/CheckoutErrorDetail' coded_recovery: type: boolean description: >- Present and true when the company routes checkout refusals by `error_details` (CHECKOUT_CODED_REFUSALS). Temporary; removed with that flag. CheckoutErrorDetail: description: >- One refusal reason, in the same vocabulary as `checkout_blockers`, with where to send the shopper and what happened to the payment. type: object additionalProperties: false required: - code - field - payment - message properties: code: type: string description: Stable refusal code. Codes reuse the `checkout_blockers` codes. field: type: - string - 'null' description: >- The cart API path to send the shopper to, for example `shipping_address.postal_code` or `items[123]`, or null. payment: type: string enum: - not_attempted - declined - unknown - held description: >- `not_attempted`: fix the cause and resubmit. `declined`: the payment was refused; resubmit with another method. `declined` reflects the stored payment status; for some gateways an unconfirmed failure is still reported as `declined`. `unknown`: money may have moved; check the order before charging again. `held`: the cart's only money is the payment a resubmit reuses. Fix the field and resubmit with the same payment method; checkout will not charge again. message: type: string description: The English message for this entry. Not translated. CheckoutCartSubscriptionStartNotice: description: >- The checkout message of the merchant's blackout rule that moved a first bill date off a blocked day of the month. Informational only. type: object additionalProperties: false required: - message - moved_from properties: message: type: string description: >- The rule's checkout message. Never empty; a rule without a message gives no notice. example: >- We never bill on the 29th to the 31st, so your first order bills on the 28th. moved_from: type: string format: date description: The first bill date before the move, in the cart's time zone. example: '2026-11-30' CheckoutCartItemError: description: >- Per-line checkout error entry (CartItem#item_checkout_errors). A map of error key (product, country, enrollment_pack, quantity, customer_limit, subscription_max_qty, bundle_customer_limit, bundle_subscription_max_qty) to an array of localized messages. `enrollment_pack` means the line's enrollment pack was discarded or deleted; the shopper removes the pack to continue. 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 default: description: >- True when this plan is the product's own default plan. Informational: it does not mark the preselected plan. The list puts the plan the line is offered first (the line's own plan, else the product's own default), so a client that preselects a plan reads the first entry. type: boolean 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' apply_to_volume: description: >- Reduce this plan's line CV/QV by the same percentage as its subscription price discount. 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 required: - id - title - image_url - image_path - cv - tax - sku - external_id - canonical_url - introduction - price - price_in_currency - tax_in_currency - subscription_price - metadata - metafields - metafields_collection 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 required: - id - title - display_name - image_url - image_path - sku - primary_image - price - price_in_currency - currency_code - options - physical - unit_of_size - height - width - length - unit_of_weight - weight - hs_code 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' regular_line_total_in_currency: type: - string - 'null' description: >- Unavailable (null): a bundle price for this tier cannot be computed; checkout refuses the line. 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' currency_code: description: >- Currency of this entry's amounts, stamped by the server on write; client values are ignored. Absent on legacy entries and entries without amounts. 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' 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' 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' active: type: boolean description: >- Whether the bundled variant and its product are both active and kept. Active/kept state only: excludes inventory, and country is carried separately by available_country_codes. 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 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.