> ## 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 <token>; 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.

# Create subscription bundle

> Creates a subscription bundle from the supplied `bundle` definition.
Requires a bearer token. Returns `422` on validation failure and `401`
when unauthenticated.




## OpenAPI

````yaml /api-reference/checkout-v2026-04.yaml post /api/checkout/v2026-04/subscription_bundles
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/subscription_bundles:
    post:
      tags:
        - subscription-bundles
      summary: Create subscription bundle
      description: |
        Creates a subscription bundle from the supplied `bundle` definition.
        Requires a bearer token. Returns `422` on validation failure and `401`
        when unauthenticated.
      operationId: checkout_v2026_04_create_subscription_bundle
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                bundle:
                  type: object
                  properties:
                    subscription_tokens:
                      type: array
                      items:
                        type: string
                      description: Subscription tokens to bundle
                    address_id:
                      type:
                        - integer
                        - 'null'
                    next_bill_date:
                      description: >-
                        ISO 8601 date-time accepted by BundleAction.
                        Subscription bundle responses serialize the resulting
                        grouped local bill date as a date.
                      type: string
                      format: date-time
                    volume_rep_id:
                      type:
                        - integer
                        - 'null'
                  required:
                    - subscription_tokens
                    - next_bill_date
                  additionalProperties: false
              required:
                - bundle
              additionalProperties: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutSubscriptionBundleResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearer_auth: []
components:
  schemas:
    CheckoutSubscriptionBundleResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        subscription_bundle:
          $ref: '#/components/schemas/CheckoutSubscriptionBundle'
      required:
        - meta
        - subscription_bundle
      additionalProperties: false
    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'
    Meta:
      type: object
      properties:
        request_id:
          type:
            - string
            - 'null'
        timestamp:
          type: string
          format: date-time
    CheckoutSubscriptionBundle:
      type: object
      properties:
        address:
          oneOf:
            - $ref: '#/components/schemas/CheckoutAddress'
            - type: 'null'
        next_bill_date:
          description: >-
            Local bill date used for bundle grouping. Create requests accept a
            date-time, but bundle responses serialize the grouped local date
            only.
          type:
            - string
            - 'null'
          format: date
        subscription_count:
          type: integer
        subscriptions:
          type: array
          items:
            $ref: '#/components/schemas/CheckoutSubscriptionBundleItem'
        volume_rep:
          oneOf:
            - $ref: '#/components/schemas/CheckoutSubscriptionBundleVolumeRep'
            - type: 'null'
      required:
        - address
        - next_bill_date
        - subscription_count
        - subscriptions
        - volume_rep
      additionalProperties: false
    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
    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
    CheckoutSubscriptionBundleItem:
      type: object
      properties:
        currency:
          $ref: '#/components/schemas/CheckoutSubscriptionBundleCurrency'
        id:
          type: integer
        original_price:
          type: number
        price:
          type: number
        subscription_plan_name:
          type:
            - string
            - 'null'
        subscription_token:
          type: string
        variant:
          oneOf:
            - $ref: '#/components/schemas/CheckoutSubscriptionBundleVariant'
            - type: 'null'
      required:
        - currency
        - id
        - original_price
        - price
        - subscription_plan_name
        - subscription_token
        - variant
      additionalProperties: false
    CheckoutSubscriptionBundleVolumeRep:
      type: object
      properties:
        id:
          type: integer
        email:
          type: string
        full_name:
          type: string
        image_url:
          type:
            - string
            - 'null'
      required:
        - id
        - email
        - full_name
        - image_url
      additionalProperties: false
    ErrorValue:
      description: A validation or API error value.
      anyOf:
        - type: string
        - type: array
          items:
            type: string
        - type: object
          additionalProperties:
            $ref: '#/components/schemas/JsonValue'
    CheckoutSubscriptionBundleCurrency:
      type: object
      properties:
        active:
          type: boolean
        code:
          type: string
        id:
          type: integer
        name:
          type: string
        rate:
          type:
            - number
            - string
        symbol:
          type: string
      required:
        - active
        - code
        - id
        - name
        - rate
        - symbol
      additionalProperties: false
    CheckoutSubscriptionBundleVariant:
      type: object
      properties:
        currency_code:
          type:
            - string
            - 'null'
        display_name:
          type:
            - string
            - 'null'
        id:
          type: integer
        image_path:
          type:
            - string
            - 'null'
        image_url:
          type:
            - string
            - 'null'
        options:
          type: array
          items:
            $ref: '#/components/schemas/CheckoutProductVariantOption'
        price:
          type:
            - number
            - string
            - 'null'
        price_in_currency:
          type: string
        primary_image:
          type:
            - string
            - 'null'
        product:
          $ref: '#/components/schemas/CheckoutSubscriptionBundleProduct'
        sku:
          type:
            - string
            - 'null'
        title:
          type:
            - string
            - 'null'
      required:
        - currency_code
        - display_name
        - id
        - image_path
        - image_url
        - options
        - price
        - price_in_currency
        - primary_image
        - product
        - sku
        - title
      additionalProperties: false
    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'
    CheckoutProductVariantOption:
      type: object
      properties:
        title:
          type: string
        value:
          type: string
      required:
        - title
        - value
      additionalProperties: false
    CheckoutSubscriptionBundleProduct:
      type: object
      properties:
        canonical_url:
          type: string
        cv:
          type:
            - string
            - 'null'
          format: decimal
        cv_in_currency:
          type: string
        external_id:
          type:
            - string
            - 'null'
        id:
          type: integer
        image_path:
          type:
            - string
            - 'null'
        image_url:
          type:
            - string
            - 'null'
        introduction:
          type:
            - string
            - 'null'
        metadata:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/JsonValue'
        metafields:
          type: array
          items:
            $ref: '#/components/schemas/JsonValue'
        price:
          type:
            - number
            - string
            - 'null'
        price_in_currency:
          type: string
        product_bundle_groups:
          description: Present only when the serialized product is itself a bundle product.
          type: array
          items:
            $ref: '#/components/schemas/JsonValue'
        sku:
          type:
            - string
            - 'null'
        tax:
          type:
            - number
            - string
            - 'null'
        tax_in_currency:
          type: string
        title:
          type: string
      required:
        - canonical_url
        - cv
        - cv_in_currency
        - external_id
        - id
        - image_path
        - image_url
        - introduction
        - metadata
        - metafields
        - price
        - price_in_currency
        - sku
        - tax
        - tax_in_currency
        - title
      additionalProperties: false
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
      description: Bearer token authentication

````