> ## Documentation Index > Fetch the complete documentation index at: https://docs.fluid.app/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > For new direct REST integrations, use the v2026-04 surfaces. The @fluid-app FairShare SDK continues to use its own published public-v2025-06 contract. > Authenticate with the header Authorization: Bearer ; public storefront read endpoints require no auth. > Lists use cursor pagination via the page[cursor] and page[limit] query params; follow meta.pagination.next_cursor until it is null. > Never use /api/company/v1 or /api/v1 paths, page/per_page params, or offset pagination — they are legacy. > The OpenAPI specs under api-reference/ are the authoritative contracts; prefer them over prose when in doubt. api-reference/storefront-v2026-04.yaml covers the v2026-04 storefront surface (/api/v202604/... paths); api-reference/auth-v0.yaml covers the unversioned auth surface (/api/... paths — authentication, MFA, social auth, and token exchange); api-reference/checkout-v2026-04.yaml covers the v2026-04 checkout surface (/api/checkout/v2026-04/... paths — carts, cart auth, discounts, items, subscriptions, orders, enrollments, and store config); api-reference/public-v2025-06.yaml covers the Public SDK surface used by the @fluid-app FairShare SDK, including its parallel cart lifecycle, browser integrations, versioned payment callbacks, unversioned public utilities, and the cart price-override operation; api-reference/payment-v2026-04.yaml covers the v2026-04 payment gateway admin surface (/api/payment/v2026-04/... paths, bearer-authenticated — gateway CRUD, gateway purchase/authorize/$0-verify, transaction list/show and capture/void/credit, and merchant payment configuration); api-reference/payments-v2026-04.yaml covers the v2026-04 cart payment surface (/api/payments/v2026-04/carts/{cart_token}/... paths, authenticated by the cart token in the path with no bearer — payment-method selection, VGS card tokenization, 3D Secure verification, and PayPal/Braintree/Klarna/Apple Pay flows); api-reference/commerce-v2026-04.yaml covers the v2026-04 commerce order-editing surface (/api/v202604/orders/{order_id}/edits paths, bearer-authenticated — post-checkout order edits that atomically insert items and add adjustments/discounts, with an optional dry-run preview); api-reference/webhooks-v0.yaml covers the unversioned webhooks surface (/api/... paths — webhook registration, delivery payloads, callback registrations, company events, and webhook/callback schemas). > Successful responses wrap the resource payload alongside a top-level integer status and a meta object. # Apply manual discount (admin only) > Creates a one-time manual discount and applies it to the cart. Requires admin authentication (root_or_admin? role). Manual discounts are single-use, require a reason, and are excluded from the promo code management UI. ## OpenAPI ````yaml /api-reference/checkout-v2026-04.yaml post /api/checkout/v2026-04/carts/{cart_token}/discount/manual openapi: 3.1.0 info: title: Fluid Checkout API description: >- **Fluid Checkout API — for building a checkout directly against REST.** Use this surface if you are integrating server-to-server or building your own checkout UI. It covers the full order lifecycle (cart → address → shipping → discount → complete → order) plus the logged-in customer's account: saved addresses, saved payment methods, order history, loyalty points, and subscription management (pause, resume, skip, cancel, retry). **The cart token in the URL scopes cart access** — creating a cart, adding items, applying a discount, and completing a cart need no bearer token. Among the cart operations, a Bearer token is required only for `carts/{cart_token}/sync`, `carts/{cart_token}/volume_rep`, and `carts/{cart_token}/discount/manual`. Off the cart, a token is required for everything under `customers/me` and `subscriptions`, and for the store and directory lookups (`store/config`, `store/languages`, `reps`, `users`) and `subscription_bundles`. `store/countries` accepts a token but does not require one — it returns the same list either way. **If you are using the `@fluid-app` FairShare SDK in a theme or storefront, you are not calling this surface** — the SDK calls the Fluid Public SDK API (`public-v2025-06`). Do not mix the two against one cart: they share the same cart records and services, but their request shapes differ. See [Choosing a cart surface](https://docs.fluid.app/api/choosing-a-cart-surface) for the operation map and boundary. version: v2026-04 contact: email: support@fluid.app license: name: Proprietary identifier: LicenseRef-Proprietary servers: - url: https://api.fluid.app security: [] tags: - name: carts description: >- Create, read, and mutate checkout carts (email, address, country, language, shipping, recalculation, completion). - name: cart-auth description: >- Cart-scoped customer authentication — magic-link challenge, verification, identity, and logout. - name: cart-discount description: >- Apply, list, and remove cart discount codes, including admin manual discounts. - name: cart-items description: Add, update, and remove line items on a cart. - name: cart-points description: Apply and remove loyalty points on a cart. - name: customers description: The authenticated customer's profile and company memberships. - name: customer-addresses description: The authenticated customer's saved shipping/billing addresses. - name: customer-orders description: The authenticated customer's order history. - name: customer-payment-methods description: The authenticated customer's saved payment methods and tokenization. - name: customer-points description: The authenticated customer's loyalty point balances. - name: directory description: Company rep and user directory lookups. - name: enrollments description: >- Public enrollment forms — retrieve a form and submit, update, or upload field answers. - name: orders description: Public order lookup by token. - name: products description: Public product queries for the storefront checkout. - name: store description: >- Store-level checkout configuration — countries, languages, address fields, agreements, drop zones, and Apple Pay domain verification. - name: subscriptions description: >- Manage subscriptions — pause, resume, skip, cancel, reactivate, retry, and failed-cycle waivers. - name: subscription-bundles description: List and create subscription bundles. paths: /api/checkout/v2026-04/carts/{cart_token}/discount/manual: post: tags: - cart-discount summary: Apply manual discount (admin only) description: >- Creates a one-time manual discount and applies it to the cart. Requires admin authentication (root_or_admin? role). Manual discounts are single-use, require a reason, and are excluded from the promo code management UI. operationId: checkout_v2026_04_apply_manual_discount parameters: - name: cart_token in: path required: true description: Cart token schema: type: string requestBody: required: true content: application/json: schema: type: object additionalProperties: false properties: reason: type: string description: Explanation for the manual discount (required) example: VIP customer courtesy price_discount_type: type: string enum: - flat - percentage description: Discount type example: flat flat_value: type: number format: float description: Dollar amount (required when price_discount_type is flat) example: 10 percentage_value: type: number format: float description: >- Percentage 0-100 (required when price_discount_type is percentage) example: 15 applicable_for: type: string enum: - everything - specific_products - specific_collections - except_specific_products description: Product targeting scope apply_to_subscriptions: type: boolean default: false description: >- Whether the discount applies to subscription line items in the current cart apply_to_recurring_subscription_orders: type: boolean description: >- Whether the discount carries forward to recurring orders spawned from the cart. Requires apply_to_subscriptions to be true. When omitted, defaults to the value of apply_to_subscriptions. apply_to_volume: type: boolean default: false description: Whether the discount reduces QV/CV totals required: - reason - price_discount_type responses: '200': description: Discount created and applied content: application/json: schema: allOf: - $ref: '#/components/schemas/CartResponse' - type: object properties: meta: type: object properties: totals_stale: type: boolean description: >- Present and true when cart recalculation failed after the discount was applied. The discount is linked but totals may be outdated. '401': description: Unauthorized — missing/invalid JWT or non-admin role content: application/json: schema: anyOf: - $ref: '#/components/schemas/UnauthorizedResponse' - type: object properties: errors: type: object properties: auth: type: array items: type: string example: - admin authentication required '410': $ref: '#/components/responses/ProcessedCartResponse' '422': description: Validation failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearer_auth: [] components: schemas: CartResponse: description: >- Cart response wrapper (CartBlueprinter with_associations view). Scalar totals, flags, and points are strictly typed; genuinely dynamic fields (metadata, processor-specific payment payloads) and nested associations (items, addresses, country, company) are typed as open pockets and tightened in follow-up work. type: object required: - cart - meta additionalProperties: false properties: cart: type: object additionalProperties: false properties: id: type: integer description: Numeric primary key of the cart row. cart_token: type: string description: > Opaque cart token. This is the value that scopes every subsequent cart operation as `{cart_token}`. Store it in your session after create-cart. state: type: string description: | Current lifecycle state of the cart. A completed cart is locked; mutations against it return `410`. state_revision: type: integer format: int64 minimum: 0 description: Monotonic ordering marker for published cart snapshots. type: type: - string - 'null' description: >- Cart type discriminator (e.g. enrollment vs standard); `null` when unset. email: type: - string - 'null' description: Buyer email captured on the cart; `null` until set. phone: type: - string - 'null' description: Buyer phone captured on the cart; `null` until set. language_iso: type: - string - 'null' description: >- ISO language code driving localized content; `null` when not set. currency_code: type: - string - 'null' description: >- ISO 4217 currency code the cart prices in; `null` until resolved. currency_symbol: type: string description: Display symbol for `currency_code` (e.g. `$`). currency_decimal_places: type: integer description: >- Number of fractional digits used when formatting money in this currency. customer_id: type: - integer - 'null' description: >- Id of the customer the cart is bound to, or `null` for an anonymous cart. buyer_rep_id: type: - integer - 'null' description: >- Id of the attributed buyer rep, or `null` when there is no attribution. enrollment_pack_id: type: - integer - 'null' description: Id of the enrollment pack seeded on the cart, or `null`. processed: type: boolean description: > `true` once the cart has been completed into an order. A processed cart is locked — further mutations return `410`. email_marketing: type: - boolean - 'null' description: >- Email marketing opt-in captured for the buyer; `null` when not asked. sms_marketing: type: - boolean - 'null' description: >- SMS marketing opt-in captured for the buyer; `null` when not asked. cv_total: type: - string - 'null' format: decimal qv_total: type: - string - 'null' format: decimal amount_total: type: number description: >- Grand total the buyer pays, in the cart currency (items + tax + shipping - discounts). sub_total: type: number description: Sum of line-item prices before tax, shipping, and discounts. tax_total: type: number description: Total tax on the cart. shipping_total: type: number description: Total shipping charge for the selected method. discount_total: type: number description: Total value of all applied discounts. subtotal_after_discounts: type: number description: >- Item subtotal after discounts are applied, before tax and shipping. transaction_fee: type: number description: Any transaction/processing fee added to the cart. enrollment_fee: type: - number - string - 'null' description: Enrollment fee applied to the cart, or `null` when none applies. inclusive_shipping_tax: type: number description: >- Portion of `shipping_total` that is embedded tax (tax-inclusive pricing). shipping_discount: type: number description: Discount applied specifically to shipping. remaining_cart_amount_after_points: type: number description: Amount still due after applying loyalty points. amount_total_in_currency: type: string sub_total_in_currency: type: string tax_total_in_currency: type: string shipping_total_in_currency: type: string discount_total_in_currency: type: string subtotal_after_discounts_in_currency: type: string transaction_fee_in_currency: type: string enrollment_fee_in_currency: type: string customer_total_points_in_currency: type: string points_applied_amount_in_currency: type: string remaining_customer_points_amount_in_currency: type: string remaining_cart_amount_after_points_in_currency: type: string tax_total_for_display: type: string shipping_total_for_display: type: string tax_exempt: type: boolean description: '`true` when the cart is exempt from tax.' digital_only: type: boolean description: '`true` when every line item is digital (no physical shipment).' immutable_items: type: boolean description: >- `true` when the cart's line items are locked and cannot be changed. points_enabled: type: boolean description: '`true` when loyalty points may be applied to this cart.' price_inclusive_of_tax: type: boolean description: '`true` when catalog prices already include tax.' requires_3ds: type: boolean description: >- `true` when the selected payment requires a 3D Secure challenge before completion. requires_payment_method: type: boolean description: >- `true` when a payment method must be supplied before the cart can complete. vault_without_charge: type: boolean description: >- `true` when a payment method is vaulted without an immediate charge. valid_for_checkout: type: boolean description: >- `true` when the cart passes all validations and can be completed into an order. valid_for_checkout_pre_payment: type: boolean description: >- `true` when the cart is valid up to the payment step (everything but payment is satisfied). payment_method_auto_assignable: type: boolean description: >- `true` when a payment method can be auto-assigned without buyer input. customer_total_points: type: integer points_applied: type: integer remaining_customer_points: type: integer max_applicable_points: type: integer total_creditable_points: type: integer totals: type: object additionalProperties: false required: - gross_subtotal - gross_subtotal_in_currency - net_subtotal - net_subtotal_in_currency - item_tax - item_tax_in_currency - shipping_net - shipping_net_in_currency - shipping_tax - shipping_tax_in_currency - total_tax - total_tax_in_currency - price_inclusive_of_tax - tax_label description: >- Display-ready totals breakdown sourced from Commerce::Totals (STU2-2580). Decomposes the inclusive-tax figures so clients render the net subtotal, item tax, shipping net and shipping VAT without re-deriving them. Each money component carries a raw boundary-rounded decimal string plus its currency-formatted `_in_currency` sibling. properties: gross_subtotal: type: string description: Catalog sum of line-item prices (customer display). gross_subtotal_in_currency: type: string net_subtotal: type: string description: Items subtotal excluding embedded item tax. net_subtotal_in_currency: type: string item_tax: type: string description: Embedded tax attributable to the items. item_tax_in_currency: type: string shipping_net: type: string description: Shipping charge excluding embedded shipping tax. shipping_net_in_currency: type: string shipping_tax: type: string description: Embedded tax attributable to shipping. shipping_tax_in_currency: type: string total_tax: type: string description: Combined item and shipping tax. total_tax_in_currency: type: string price_inclusive_of_tax: type: boolean description: Whether catalog prices include tax. tax_label: type: - string - 'null' description: The resolved tax-line label (e.g. "VAT"), or null. price_inclusive_tax_name: type: - string - 'null' payment_account: type: - string - 'null' discount_codes: type: array description: Discount codes currently applied to the cart. items: type: string product_discount_codes: type: array description: Applied discount codes that target products. items: type: string shipping_discount_codes: type: array description: Applied discount codes that target shipping. items: type: string buyer_rep: type: - object - 'null' additionalProperties: false properties: id: type: integer email: type: - string - 'null' full_name: type: - string - 'null' image_url: type: - string - 'null' external_id: type: - string - 'null' volume_rep: type: - object - 'null' additionalProperties: false properties: id: type: integer email: type: - string - 'null' full_name: type: - string - 'null' image_url: type: - string - 'null' shipping_method: type: - object - 'null' additionalProperties: false description: >- The shipping method currently selected on the cart; `null` when none is selected. properties: id: type: string description: >- Identifier of the selected shipping method (pass this as `shipping_method_id` when selecting). name: type: string description: Display name of the selected shipping method. discount_breakdown: type: object additionalProperties: false description: Breakdown of discount totals by source. properties: internal_discounts: type: number description: Total value of Fluid-internal discounts. external_discounts: type: number description: Total value of externally sourced discounts. total_discounts: type: number description: Combined discount total. available_shipping_methods: type: array description: > Shipping methods available for the cart's destination. Populated once a shipping address is set; select one by passing its `id` as `shipping_method_id`. items: type: object additionalProperties: false properties: id: type: - integer - string description: Identifier of the available shipping method. title: type: - string - 'null' description: Display name of the method. price: type: - number - string - 'null' description: Price of the method in the cart currency. delivery_time_estimate: type: - string - 'null' description: Human-readable delivery estimate, when available. price_label: type: - string - 'null' description: Preformatted price label for display. metadata: type: - object - 'null' additionalProperties: true messages: $ref: '#/components/schemas/JsonValue' payment_method: $ref: '#/components/schemas/CheckoutCartPaymentMethod' available_payment_methods: type: array items: $ref: '#/components/schemas/CheckoutAvailablePaymentMethod' external_discount: $ref: '#/components/schemas/CheckoutExternalDiscount' shipping_address: $ref: '#/components/schemas/CheckoutAddressData' billing_address: $ref: '#/components/schemas/CheckoutAddressData' items: type: array description: The cart's line items. items: $ref: '#/components/schemas/CheckoutCartItem' ship_to: description: Resolved shipping address on the cart; `null` when none is set. anyOf: - type: 'null' - $ref: '#/components/schemas/CheckoutAddress' bill_to: description: Resolved billing address on the cart; `null` when none is set. anyOf: - type: 'null' - $ref: '#/components/schemas/CheckoutAddress' attribution: $ref: '#/components/schemas/CheckoutAttribution' agreements: type: array items: $ref: '#/components/schemas/CheckoutAgreement' country: $ref: '#/components/schemas/CheckoutCountry' company: $ref: '#/components/schemas/CheckoutCompany' recurring: type: array items: $ref: '#/components/schemas/CheckoutCartRecurringItem' enrollment_pack: $ref: '#/components/schemas/CheckoutEnrollmentPack' meta: type: object additionalProperties: false properties: shop_url: type: string description: Base storefront URL for the cart's shop. checkout_url: type: string description: Hosted checkout URL for this cart. request_id: type: - string - 'null' description: Correlation id for the request, or `null`. timestamp: type: string format: date-time description: ISO 8601 time the response was generated. totals_stale: type: boolean description: >- Present (true) on the manual-discount response when cart recalculation failed after applying the discount. UnauthorizedResponse: type: object properties: message: type: string required: - message ErrorResponse: type: object additionalProperties: false required: - error_message - errors - meta properties: error_message: type: string errors: $ref: '#/components/schemas/ErrorBag' meta: $ref: '#/components/schemas/CheckoutMeta' JsonValue: description: >- Any valid JSON value for provider, integration, theme, metadata, or other dynamic payloads whose keys are not fixed by the API contract. anyOf: - type: string - type: number - type: boolean - type: 'null' - type: array items: $ref: '#/components/schemas/JsonValue' - type: object additionalProperties: $ref: '#/components/schemas/JsonValue' CheckoutCartPaymentMethod: description: >- Cart payment_method rendered by Commerce::CartBlueprinter::PaymentMethodFormatter. A closed polymorphic union across processors (CreditCard, Paypal, Affirm, Klarna, and a simple {id,type} fallback for all others). Nullable when the cart has no payment method. type: - object - 'null' additionalProperties: false properties: id: type: integer type: type: string description: Processor class (CreditCard, Paypal, Affirm, Klarna, Droplet, ...). payment_method_type: type: - string - 'null' card_network: type: - string - 'null' last_four: type: - string - 'null' exp_month: type: - string - integer - 'null' exp_year: type: - string - integer - 'null' logo_url: type: - string - 'null' status: type: - string - 'null' affirm_id: type: - string - integer - 'null' checkout_id: type: - string - integer - 'null' created: type: - string - integer - 'null' auth_expiration: type: - string - integer - 'null' currency: type: - string - 'null' amount: type: - number - string - 'null' session_id: type: - string - 'null' intent: type: - string - 'null' customer_details: type: object additionalProperties: true CheckoutAvailablePaymentMethod: description: >- Available payment method entry rendered by Commerce::CartsService#available_payment_methods_as_hash. Common envelope fields are strictly typed; processor-specific fields vary by gateway. type: object additionalProperties: true required: - id - uuid - type - name - image_url - test - sandbox - customer_details_schema properties: id: type: integer uuid: type: - string - 'null' type: type: string name: type: string image_url: type: - string - 'null' test: type: boolean sandbox: type: boolean collect_billing_address: type: boolean customer_details_schema: description: >- Map of required customer-info fields keyed by field name (e.g. phone, document_id); each gateway's required_customer_info_schema emits entries of {label, type, required} (empty object for most gateways). type: object additionalProperties: type: object additionalProperties: false required: - label - type - required properties: label: type: string type: type: string required: type: boolean supported_brands: type: array items: type: string token_provider: type: - string - 'null' tokenize_path: type: - string - 'null' bogus_gateway: type: boolean apple_pay: type: boolean apple_pay_recurring_supported: type: boolean apple_pay_merchant_identifier: type: - string - 'null' client_id: type: - string - 'null' merchant_id: type: - string - 'null' sdk_type: type: - string - 'null' decrypted_apple_pay_via_paypal: type: boolean integration_key: type: - string - 'null' CheckoutExternalDiscount: description: >- External (third-party) discount metadata rendered by Commerce::CartBlueprinter#external_discount_metadata. `sources` is a map keyed by discount-source identifier. type: - object - 'null' additionalProperties: false properties: total: type: number calculated_at: type: - string - 'null' format: date-time sources: type: object description: >- Map of discount-source id -> source entry. Each entry carries at least a rounded `amount`. additionalProperties: type: object additionalProperties: true properties: amount: type: - number - 'null' CheckoutAddressData: description: >- Cart shipping_address / billing_address snapshot rendered by AddressModel::Service#data (address_model.to_h). Distinct from CheckoutAddress - carries no id, country_num_code, or default. Nullable when the underlying snapshot is blank. type: - object - 'null' additionalProperties: false properties: name: type: - string - 'null' address1: type: - string - 'null' address2: type: - string - 'null' address3: type: - string - 'null' city: type: - string - 'null' state: type: - string - 'null' postal_code: type: - string - 'null' country_code: type: - string - 'null' subdivision_code: type: - string - 'null' phone: type: - string - 'null' CheckoutCartItem: description: >- Cart line item rendered by Commerce::CartItemBlueprinter (:cart view), including nested product and variant. type: object additionalProperties: false properties: id: type: integer description: Line-item id. Pass it as `{id}` to update or remove this line. title: type: - string - 'null' description: Display title of the line item. quantity: type: integer description: Quantity of the variant on this line. price: type: - number - string - 'null' description: Unit price of the line item in the cart currency. discount_amount: type: - number - string - 'null' description: Discount applied to this line. tax: type: - number - string - 'null' description: Tax attributable to this line. cv: type: - string - 'null' format: decimal qv: type: - string - 'null' format: decimal cv_total: type: - string - 'null' format: decimal qv_total: type: - string - 'null' format: decimal total: type: - number - string - 'null' description: Line total before discounts (unit price times quantity). total_after_discounts: type: - number - string - 'null' description: Line total after this line's discounts are applied. enrollment_pack_id: type: - integer - 'null' description: Enrollment pack this line belongs to, or `null`. subscription: type: - boolean - 'null' description: '`true` when this line is a subscription item.' display_to_customer: type: - boolean - 'null' description: >- `true` when the line is shown to the customer (bundle children may be hidden). image_url: type: - string - 'null' description: Image URL for the line item. price_in_currency: type: - string - 'null' description: Currency-formatted unit price for display. tax_in_currency: type: - string - 'null' description: Currency-formatted line tax for display. discount_amount_in_currency: type: - string - 'null' total_in_currency: type: - string - 'null' total_after_discounts_in_currency: type: - string - 'null' line_total_in_currency: type: - string - 'null' line_total_after_discounts_in_currency: type: - string - 'null' unit_price_display_authoritative: type: - boolean - 'null' free_item: type: - boolean - 'null' description: '`true` when the line is a free/gift item.' allow_subscription: type: - boolean - 'null' description: '`true` when this line may be converted to a subscription.' enrollment: type: - boolean - 'null' description: '`true` when the line is part of an enrollment.' creditable_points: type: - integer - 'null' description: Loyalty points this line can earn, or `null`. product_title: type: - string - 'null' description: Title of the underlying product. subscription_plan_id: type: - integer - 'null' description: >- Id of the subscription plan for a subscription line; `null` otherwise. subscription_only: type: - boolean - 'null' description: '`true` when the variant can only be purchased as a subscription.' subscription_interval: type: - integer - string - 'null' subscription_interval_unit: type: - string - 'null' subscription_interval_unit_identifier: type: - string - 'null' subscription_price: type: - number - string - 'null' subscription_price_in_currency: type: - string - 'null' subscription_start: type: - string - 'null' subscribe_and_save: type: - number - string - 'null' subscribe_and_save_in_currency: type: - string - 'null' subscribe_and_save_for_display: type: - string - 'null' metadata: type: - object - 'null' additionalProperties: true errors: type: array description: Per-item checkout errors (cart_item.item_checkout_errors). items: $ref: '#/components/schemas/CheckoutCartItemError' subscription_plans: type: array description: >- Subscription plans rendered by SubscriptionPlanBlueprinter (:cart_item view). items: $ref: '#/components/schemas/CheckoutCartItemSubscriptionPlan' bundled_items: type: array description: >- Bundle child selections (metadata-derived, customer-visible entries only in the :cart view). items: $ref: '#/components/schemas/CheckoutBundledItem' product: $ref: '#/components/schemas/CheckoutProduct' variant: $ref: '#/components/schemas/CheckoutVariant' CheckoutAddress: description: Resolved address on a cart (AddressBlueprinter default view). type: object properties: address1: type: string description: Primary street line of the address. address2: type: 'null' description: Second address line; always `null` in this view. address3: type: 'null' description: Third address line; always `null` in this view. city: type: string description: City / locality. country_code: type: string description: ISO 3166-1 alpha-2 country code (e.g. `US`). country_num_code: type: integer description: ISO 3166-1 numeric country code. default: type: boolean description: '`true` when this is the customer''s default address.' id: type: - integer - 'null' description: >- Persisted address id, or `null` for an unsaved/wallet-partial address. name: type: - string - 'null' description: >- Recipient name; `null` for wallet-partial addresses that are privacy-scrubbed until approval. phone: type: - string - 'null' description: Contact phone for the address; `null` when unset. postal_code: type: string description: Postal / ZIP code. state: type: string description: State / province / region. subdivision_code: type: 'null' description: ISO subdivision code; always `null` in this view. required: - address1 - address2 - address3 - city - country_code - country_num_code - default - id - name - phone - postal_code - state - subdivision_code additionalProperties: false CheckoutAttribution: description: >- Cart attribution rendered by AttributionBlueprinter. Emits `id` plus exactly one attribution-type key (the cart's attributable_type) whose value is the attributable_id. Nullable when the cart has no attribution. type: - object - 'null' additionalProperties: false properties: id: type: integer email: type: - integer - string - 'null' fluid_rep_id: type: - integer - string - 'null' external_id: type: - integer - string - 'null' share_guid: type: - integer - string - 'null' username: type: - integer - string - 'null' CheckoutAgreement: description: Checkout agreement rendered by AgreementBlueprinter (default view). type: object additionalProperties: false properties: id: type: integer title: type: - string - 'null' show_at_checkout: type: - boolean - 'null' default_checked: type: - boolean - 'null' show_path: type: - string - 'null' enrollment_pack_id: type: - integer - 'null' required: type: boolean description: >- Whether the agreement must be accepted at checkout (mirrors Agreement#required_on_checkout, coerced to a strict boolean). CheckoutCountry: type: object properties: currency_code: type: string currency_symbol: type: string id: type: integer iso: type: string iso3: type: string iso_name: type: string name: type: string price_inclusive_of_tax: type: boolean price_inclusive_tax_name: type: string province_required: type: boolean tax_enabled: type: - boolean - 'null' tax_standard_rate: type: - number - 'null' description: Standard tax rate (percent) used for inclusive-pricing countries required: - currency_code - currency_symbol - id - iso - iso3 - iso_name - name - price_inclusive_of_tax - price_inclusive_tax_name - province_required - tax_enabled - tax_standard_rate additionalProperties: false CheckoutCompany: type: object properties: bundle_subscriptions: type: boolean checkout_primary_button_color: type: - string - 'null' checkout_primary_text_color: type: - string - 'null' checkout_secondary_button_color: type: - string - 'null' checkout_secondary_text_color: type: - string - 'null' collect_email_marketing: type: boolean collect_phone: type: boolean collect_sms_marketing: type: boolean favicon_url: type: - string - 'null' fluid_shop: type: string id: type: integer isolated_payment_tokens: type: boolean kount_environment: type: string enum: - sandbox - production example: sandbox description: >- Per-merchant Kount environment. Used by the checkout DDC initializer to pick TEST vs PROD. kount_client_id: type: - string - 'null' example: '150953359757648' description: >- Per-merchant Kount Client ID (MID) for enterprise merchants. Null for portfolio merchants — the checkout app falls back to NEXT_PUBLIC_KOUNT_CLIENT_ID. logo_url: type: - string - 'null' name: type: string order_on_behalf: type: boolean primary_domain_hostname: type: string require_billing_zip: type: boolean require_phone: type: boolean reward_points_apply_to_subtotal: type: boolean reward_points_enabled: type: boolean reward_points_label_singular: type: string reward_points_label_plural: type: string subdomain: type: - string - 'null' required: - bundle_subscriptions - checkout_primary_button_color - checkout_primary_text_color - checkout_secondary_button_color - checkout_secondary_text_color - collect_email_marketing - collect_phone - collect_sms_marketing - favicon_url - fluid_shop - id - isolated_payment_tokens - kount_environment - kount_client_id - logo_url - name - order_on_behalf - primary_domain_hostname - require_billing_zip - require_phone - reward_points_apply_to_subtotal - reward_points_enabled - reward_points_label_singular - reward_points_label_plural - subdomain additionalProperties: false CheckoutCartRecurringItem: description: >- Cart recurring-charge disclosure entry produced by CartRecurringPresenter (one per subscription plan). type: object additionalProperties: false properties: subtotal: type: number subtotal_in_currency: type: - string - 'null' interval: type: - integer - 'null' interval_unit: type: - string - 'null' interval_unit_identifier: type: - string - 'null' subtotal_for_display: type: - string - 'null' start_date: type: - string - 'null' CheckoutEnrollmentPack: description: >- Cart enrollment pack rendered by EnrollmentPackBlueprinter (:cart view). Nullable when the cart has no enrollment pack. type: - object - 'null' additionalProperties: false properties: enrollment_pack_id: type: integer slug: type: - string - 'null' token: type: - string - 'null' title: type: - string - 'null' description: type: - string - 'null' enrollment_fee: type: - number - string - 'null' additional_volume: type: - integer - number - 'null' canonical_url: type: - string - 'null' enrollment_fee_in_currency: type: - string - 'null' price: type: - string - 'null' price_in_currency: type: - string - 'null' subscription_price: type: - string - 'null' subscription_price_in_currency: type: - string - 'null' images: type: array items: $ref: '#/components/schemas/CheckoutEnrollmentPackImage' items: type: array description: Enrollment pack cart items (CartItemBlueprinter :enroll_items). items: $ref: '#/components/schemas/CheckoutEnrollmentPackItem' 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: 27cf1da2-6873-4170-8369-fa402f6d2870 ErrorBag: description: >- Validation errors keyed by field, a list of errors, a single error message, or null when no structured error details are available. anyOf: - type: string - type: array items: $ref: '#/components/schemas/ErrorValue' - type: object additionalProperties: $ref: '#/components/schemas/ErrorValue' - type: 'null' CheckoutMeta: type: object additionalProperties: false required: - request_id - timestamp properties: request_id: type: - string - 'null' timestamp: type: string format: date-time CheckoutCartItemError: description: >- Per-line checkout error entry (CartItem#item_checkout_errors). A map of error key (product, country, quantity, customer_limit, subscription_max_qty, bundle_customer_limit, bundle_subscription_max_qty) to an array of localized messages. type: object additionalProperties: type: array items: type: string CheckoutCartItemSubscriptionPlan: description: >- Subscription plan rendered by SubscriptionPlanBlueprinter (:cart_item view). type: object additionalProperties: false properties: id: type: integer name: type: - string - 'null' billing_interval: type: - integer - 'null' billing_interval_unit: type: - string - 'null' description: Localized interval unit label. billing_interval_unit_identifier: type: - string - 'null' description: Raw interval unit (day, week, month, year). billing_frequency_in_words: type: - string - 'null' shipping_interval: type: - integer - 'null' shipping_interval_unit: type: - string - 'null' volume_interval: type: - integer - 'null' volume_interval_unit: type: - string - 'null' trial_period: type: - integer - 'null' trial_period_unit: type: - string - 'null' split_volume: type: - boolean - 'null' allow_max_billing_cycles: type: - boolean - 'null' max_billing_cycles: type: - integer - 'null' savings_display_mode: type: - string - 'null' savings_label: type: - string - 'null' company_default: type: - boolean - 'null' products_count: type: - integer - 'null' subscribers_count: type: - integer - 'null' price: type: - number - string - 'null' price_in_currency: type: - string - 'null' subscription_start: type: - string - 'null' format: date-time subscribe_and_save: type: - number - string - 'null' subscribe_and_save_in_currency: type: - string - 'null' subscribe_and_save_for_display: type: - string - 'null' CheckoutBundledItem: description: >- Bundle child selection stored in cart_item.metadata["bundled_items"]. Union of every writer's key set - the legacy ProductBundle path (ItemService#serialize_bundle_item) and the bundle-group path (BundleGroupPricing build_included_item_hash / build_enriched_item / propagate_source_fields). type: object additionalProperties: false properties: variant_id: type: integer product_id: type: - integer - 'null' product_title: type: - string - 'null' variant_title: type: - string - 'null' option_titles: type: array items: type: string quantity: type: integer display_to_customer: type: - boolean - 'null' product_bundle_group_id: type: - integer - 'null' group_title: type: - string - 'null' price: type: - number - string - 'null' subscription: type: - boolean - 'null' subscription_plan_id: type: - integer - 'null' CheckoutProduct: description: >- Cart item product rendered by ProductBlueprinter (:cart view). Null for orphaned line items. type: - object - 'null' additionalProperties: false properties: id: type: integer title: type: - string - 'null' image_url: type: - string - 'null' image_path: type: - string - 'null' cv: type: - string - 'null' format: decimal tax: type: - number - string - 'null' sku: type: - string - 'null' external_id: type: - string - 'null' canonical_url: type: - string - 'null' introduction: type: - string - 'null' price: type: - number - string - 'null' price_in_currency: type: - string - 'null' tax_in_currency: type: - string - 'null' subscription_price: type: - number - string - 'null' metadata: type: - object - 'null' additionalProperties: true metafields: type: array description: Metafields rendered by LegacyMetafieldBlueprint (:with_definition). items: $ref: '#/components/schemas/CheckoutProductMetafield' metafields_collection: type: array description: Product metafields_collection entries (key/value slices). items: $ref: '#/components/schemas/CheckoutEmbeddedMetafield' product_bundle_groups: type: array description: >- Present only for bundle products (ProductBlueprinter renders this association when product.bundle?). Empty/absent for regular products. items: $ref: '#/components/schemas/CheckoutProductBundleGroup' CheckoutVariant: description: >- Cart item variant rendered by VariantBlueprinter (:physical_details view = base fields + physical dimensions). Null for orphaned line items. type: - object - 'null' additionalProperties: false properties: id: type: integer title: type: - string - 'null' display_name: type: - string - 'null' image_url: type: - string - 'null' image_path: type: - string - 'null' sku: type: - string - 'null' primary_image: type: - string - 'null' price: type: - number - string - 'null' price_in_currency: type: - string - 'null' currency_code: type: - string - 'null' options: type: array items: $ref: '#/components/schemas/CheckoutVariantOption' physical: type: - boolean - 'null' unit_of_size: type: - string - 'null' height: type: - number - 'null' width: type: - number - 'null' length: type: - number - 'null' unit_of_weight: type: - string - 'null' weight: type: - string - 'null' hs_code: type: - string - 'null' CheckoutEnrollmentPackImage: description: Enrollment pack image (Image#as_json - full column dump). type: object additionalProperties: false properties: id: type: integer external_id: type: - string - 'null' image_path: type: - string - 'null' image_url: type: - string - 'null' image_url_i18n: type: object description: Map of locale -> localized image URL. additionalProperties: type: - string - 'null' position: type: - integer - 'null' relateable_id: type: integer relateable_type: type: string uuid_v7: type: string created_at: type: - string - 'null' format: date-time updated_at: type: - string - 'null' format: date-time CheckoutEnrollmentPackItem: description: >- Enrollment pack cart item rendered by Commerce::CartItemBlueprinter (:enroll_items view - base fields + product_title, minus product/variant/ discount/image fields). type: object additionalProperties: false properties: id: type: integer title: type: - string - 'null' quantity: type: integer price: type: - number - string - 'null' tax: type: - number - string - 'null' cv: type: - string - 'null' format: decimal qv: type: - string - 'null' format: decimal cv_total: type: - string - 'null' format: decimal qv_total: type: - string - 'null' format: decimal cv_in_currency: type: - string - 'null' qv_in_currency: type: - string - 'null' total: type: - number - string - 'null' total_after_discounts: type: - number - string - 'null' enrollment_pack_id: type: - integer - 'null' subscription: type: - boolean - 'null' display_to_customer: type: - boolean - 'null' price_in_currency: type: - string - 'null' tax_in_currency: type: - string - 'null' total_in_currency: type: - string - 'null' total_after_discounts_in_currency: type: - string - 'null' line_total_in_currency: type: - string - 'null' line_total_after_discounts_in_currency: type: - string - 'null' unit_price_display_authoritative: type: - boolean - 'null' allow_subscription: type: - boolean - 'null' enrollment: type: - boolean - 'null' creditable_points: type: - integer - 'null' product_title: type: - string - 'null' subscription_plan_id: type: - integer - 'null' subscription_only: type: - boolean - 'null' subscription_interval: type: - integer - string - 'null' subscription_interval_unit: type: - string - 'null' subscription_interval_unit_identifier: type: - string - 'null' subscription_price: type: - number - string - 'null' subscription_price_in_currency: type: - string - 'null' subscription_start: type: - string - 'null' subscribe_and_save: type: - number - string - 'null' subscribe_and_save_in_currency: type: - string - 'null' subscribe_and_save_for_display: type: - string - 'null' metadata: type: - object - 'null' additionalProperties: true errors: type: array items: $ref: '#/components/schemas/CheckoutCartItemError' subscription_plans: type: array items: $ref: '#/components/schemas/CheckoutCartItemSubscriptionPlan' ErrorValue: description: A validation or API error value. anyOf: - type: string - type: array items: type: string - type: object additionalProperties: $ref: '#/components/schemas/JsonValue' CheckoutProductMetafield: description: >- Product metafield rendered by LegacyMetafieldBlueprint (:with_definition view). type: object additionalProperties: false properties: id: type: integer namespace: type: - string - 'null' key: type: - string - 'null' value: $ref: '#/components/schemas/JsonValue' value_type: type: - string - 'null' description: type: - string - 'null' owner_type: type: - string - 'null' owner_id: type: - integer - 'null' created_at: type: - string - 'null' format: date-time updated_at: type: - string - 'null' format: date-time metafield_definition: $ref: '#/components/schemas/CheckoutMetafieldDefinition' CheckoutEmbeddedMetafield: description: >- Embedded metafields_collection entry (key/value slice rendered by ProductBlueprinter#metafields_collection). type: object additionalProperties: false properties: key: type: - string - 'null' value: $ref: '#/components/schemas/JsonValue' CheckoutProductBundleGroup: description: >- Product bundle group rendered by ProductBundleGroupBlueprinter. Present on bundle products only. type: object additionalProperties: false properties: id: type: integer title: type: - string - 'null' description: type: - string - 'null' group_type: type: - string - 'null' purpose: type: - string - 'null' min_selections: type: - integer - 'null' max_selections: type: - integer - 'null' selection_type: type: - string - 'null' pricing_config: type: - object - 'null' additionalProperties: true properties: pricing_type: type: - string - 'null' fixed_price: type: - number - string - 'null' min_price: type: - number - string - 'null' hidden: type: - boolean - 'null' country_pricing: type: array items: type: object additionalProperties: true properties: country_code: type: - string - 'null' enabled: type: - boolean - 'null' price: type: - string - number - 'null' wholesale: type: - string - number - 'null' subscription_price: type: - string - number - 'null' wholesale_subscription_price: type: - string - number - 'null' points: type: - string - number - 'null' cv: type: - number - string - 'null' qv: type: - number - string - 'null' wholesale_cv: type: - number - string - 'null' wholesale_qv: type: - number - string - 'null' allow_subscriptions: type: - boolean - 'null' force_subscriptions: type: - boolean - 'null' sort_order: type: - integer - 'null' created_at: type: - string - 'null' format: date-time updated_at: type: - string - 'null' format: date-time images: type: array items: $ref: '#/components/schemas/CheckoutProductBundleGroupImage' bundle_group_items: type: array items: $ref: '#/components/schemas/CheckoutBundleGroupItem' CheckoutVariantOption: description: Variant option pair rendered by VariantBlueprinter#options. type: object additionalProperties: false properties: title: type: - string - 'null' value: type: - string - 'null' CheckoutMetafieldDefinition: description: >- Metafield definition rendered by MetafieldDefinitionBlueprint (default view). Null when the metafield has no definition. type: - object - 'null' additionalProperties: false properties: id: type: integer company_id: type: - integer - 'null' namespace: type: - string - 'null' key: type: - string - 'null' name: type: - string - 'null' description: type: - string - 'null' value_type: type: - string - 'null' validation_rules: $ref: '#/components/schemas/JsonValue' owner_resource: type: - string - 'null' pinned: type: - boolean - 'null' position: type: - integer - 'null' locked: type: - boolean - 'null' list_type: type: - boolean - 'null' reference_type: type: - boolean - 'null' supported_validations: type: array items: type: string validation_description: type: - string - 'null' category_ids: type: array items: type: integer created_at: type: - string - 'null' format: date-time updated_at: type: - string - 'null' format: date-time CheckoutProductBundleGroupImage: description: Bundle group image rendered by ProductImageBlueprint (:with_dam view). type: object additionalProperties: false properties: id: type: integer image_url: type: - string - 'null' image_path: type: - string - 'null' position: type: - integer - 'null' dam_asset_code: type: - string - 'null' CheckoutBundleGroupItem: description: Bundle group item rendered by BundleGroupItemBlueprinter. type: object additionalProperties: false properties: id: type: integer quantity: type: - integer - 'null' sort_order: type: - integer - 'null' config: $ref: '#/components/schemas/CheckoutBundleGroupItemConfig' variant: $ref: '#/components/schemas/CheckoutBundleGroupItemVariant' CheckoutBundleGroupItemConfig: description: >- Resolved per-item pricing/config blob rendered by BundleGroupItemBlueprinter#config. type: object additionalProperties: false properties: price: type: - number - string - 'null' pc_price: type: - number - string - 'null' resolved_price: type: - string - 'null' resolved_wholesale_price: type: - string - 'null' resolved_cv: type: - string - 'null' format: decimal resolved_qv: type: - string - 'null' format: decimal resolved_wholesale_cv: type: - string - 'null' format: decimal resolved_wholesale_qv: type: - string - 'null' format: decimal cv: type: - string - 'null' format: decimal qv: type: - string - 'null' format: decimal pc_cv: type: - string - 'null' format: decimal pc_qv: type: - string - 'null' format: decimal is_default: type: boolean quantity: type: - integer - 'null' max_quantity: type: - integer - 'null' allow_subscription: type: boolean force_subscription: type: boolean has_subscription_plans: type: boolean subscription_plans: type: array items: $ref: '#/components/schemas/CheckoutVariantSubscriptionPricing' image_url: type: - string - 'null' available_country_codes: type: array items: type: string country_prices: type: object description: Map of ISO country code -> configured price. additionalProperties: type: - number - string - 'null' CheckoutBundleGroupItemVariant: description: >- Variant on a bundle group item rendered by VariantBlueprinter (:with_product_shallow view). type: - object - 'null' additionalProperties: false properties: id: type: integer title: type: - string - 'null' display_name: type: - string - 'null' image_url: type: - string - 'null' image_path: type: - string - 'null' sku: type: - string - 'null' primary_image: type: - string - 'null' price: type: - number - string - 'null' price_in_currency: type: - string - 'null' currency_code: type: - string - 'null' customer_limit: type: - integer - 'null' active_variant_countries: type: array items: type: string options: type: array items: $ref: '#/components/schemas/CheckoutVariantOption' product: $ref: '#/components/schemas/CheckoutBundleItemProduct' CheckoutVariantSubscriptionPricing: description: >- Per-plan subscription pricing entry rendered by V2::VariantBlueprinter.build_subscription_plans. type: object additionalProperties: false properties: id: type: integer subscription_price_in_currency: type: - string - 'null' subscribe_and_save_in_currency: type: - string - 'null' subscribe_and_save_for_display: type: - string - 'null' wholesale_subscription_price_in_currency: type: - string - 'null' wholesale_subscribe_and_save_in_currency: type: - string - 'null' wholesale_subscribe_and_save_for_display: type: - string - 'null' CheckoutBundleItemProduct: description: >- Product nested under a bundle-group-item variant, rendered by ProductBlueprinter (:item_without_bundle_groups view). type: - object - 'null' additionalProperties: false properties: id: type: integer title: type: - string - 'null' image_url: type: - string - 'null' image_path: type: - string - 'null' cv: type: - string - 'null' format: decimal cv_in_currency: type: - string - 'null' tax: type: - number - string - 'null' tax_in_currency: type: - string - 'null' sku: type: - string - 'null' external_id: type: - string - 'null' canonical_url: type: - string - 'null' introduction: type: - string - 'null' price: type: - number - string - 'null' price_in_currency: type: - string - 'null' metadata: type: - object - 'null' additionalProperties: true responses: ProcessedCartResponse: description: >- The cart is locked and can no longer be modified. Cart-mutation endpoints return this when the cart has already been processed (converted to an order) or, for enrollment carts, is in an authorized payment state. The body carries the full cart plus the store URL so the client can display the locked cart and redirect. content: application/json: schema: $ref: '#/components/schemas/LockedCartErrorResponse' securitySchemes: bearer_auth: type: http scheme: bearer description: Bearer token authentication ````