openapi: 3.0.3
info:
  title: Subbly Storefront API (Modeled)
  description: >-
    MODELED OpenAPI for Subbly's storefront developer surface. Subbly is a
    subscription-first commerce platform. Its documented developer tools are the
    client-side SubblyCart.js cart widget and the Subbly.js SDK (@subbly/sdk),
    which call Subbly's REST backend to manage products, bundles, carts,
    checkout, customers, and subscriptions. Subbly does NOT publish concrete
    REST endpoint paths, a base API host, or an official OpenAPI definition - the
    SDK abstracts them. The paths and schemas below are therefore MODELED from
    the documented SDK operations to give the catalog a workable shape; they are
    illustrative and are not an official Subbly REST contract. The public Orders
    API (3PL integration) is documented by Subbly on request and is not modeled
    here, and Subbly's webhooks are configured in the admin without a published
    payload schema.
    Authentication for the storefront SDK uses an apiKey issued in the Subbly
    admin (Shop Settings), optionally with a per-customer access token.
  version: '0.1.0-modeled'
  contact:
    name: Subbly Developers
    url: https://www.subbly.dev/
servers:
  - url: https://api.subbly.example/v1
    description: >-
      Modeled placeholder base URL. Subbly does not publish its REST API host;
      the Subbly.js SDK resolves the real host internally. Do not treat this as a
      live endpoint.
security:
  - apiKey: []
tags:
  - name: Products
    description: Storefront products and bundles (modeled from the SDK).
  - name: Cart
    description: Cart and checkout operations (modeled from the SDK and SubblyCart.js).
  - name: Customers
    description: Customer accounts, addresses, and payment methods (modeled from the SDK).
  - name: Subscriptions
    description: Customer subscriptions and preferences (modeled from the SDK).
paths:
  /products:
    get:
      operationId: listProducts
      tags:
        - Products
      summary: List products
      description: Lists storefront products. Modeled from the Subbly.js SDK products methods.
      responses:
        '200':
          description: A list of products.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Product'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /products/{id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      operationId: getProduct
      tags:
        - Products
      summary: Get a product
      description: Retrieves a product (including parent products / variants). Modeled from the SDK.
      responses:
        '200':
          description: The requested product.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '404':
          $ref: '#/components/responses/NotFound'
  /products/{id}/variants:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      operationId: listProductVariants
      tags:
        - Products
      summary: List product variants
      description: Lists the variants of a product. Modeled from the SDK.
      responses:
        '200':
          description: A list of variants.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Product'
  /bundles:
    get:
      operationId: listBundles
      tags:
        - Products
      summary: List bundles
      description: Lists bundle products. Modeled from the SDK bundle methods.
      responses:
        '200':
          description: A list of bundles.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Bundle'
  /bundles/{id}/items:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      operationId: getBundleItems
      tags:
        - Products
      summary: Get bundle items
      description: Retrieves the items available for a bundle. Modeled from the SDK.
      responses:
        '200':
          description: Bundle items.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Product'
  /bundles/{id}/quote:
    parameters:
      - $ref: '#/components/parameters/Id'
    post:
      operationId: quoteBundle
      tags:
        - Products
      summary: Generate a bundle quote
      description: Generates a price quote for a configured bundle. Modeled from the SDK.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BundleQuoteInput'
      responses:
        '200':
          description: The bundle quote.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quote'
  /carts:
    post:
      operationId: createCart
      tags:
        - Cart
      summary: Create a cart
      description: Creates a new cart. Modeled from the SDK / SubblyCart.js.
      responses:
        '201':
          description: The created cart.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cart'
  /carts/{id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      operationId: getCart
      tags:
        - Cart
      summary: Get a cart
      description: Loads a cart by ID. Modeled from the SDK.
      responses:
        '200':
          description: The requested cart.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cart'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateCart
      tags:
        - Cart
      summary: Update a cart
      description: Updates a cart (items, coupons, gift cards, shipping method, gifting date). Modeled from the SDK.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CartInput'
      responses:
        '200':
          description: The updated cart.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cart'
  /carts/{id}/items:
    parameters:
      - $ref: '#/components/parameters/Id'
    post:
      operationId: addCartItem
      tags:
        - Cart
      summary: Add a cart item
      description: Adds an item to the cart. Modeled from the SDK / SubblyCart.js addItem.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CartItemInput'
      responses:
        '200':
          description: The updated cart.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cart'
  /checkout:
    post:
      operationId: checkout
      tags:
        - Cart
      summary: Checkout and purchase
      description: >-
        Processes checkout and purchase for a cart, including payment intent
        handling with 3DS verification. Modeled from the SDK purchase flow.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutInput'
      responses:
        '200':
          description: The resulting order / purchase confirmation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '402':
          description: Payment required or requires further (3DS) action.
  /customers:
    post:
      operationId: registerCustomer
      tags:
        - Customers
      summary: Register a customer
      description: Registers a new customer. Modeled from the SDK auth methods.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerInput'
      responses:
        '201':
          description: The created customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
  /customers/sessions:
    post:
      operationId: authenticateCustomer
      tags:
        - Customers
      summary: Authenticate a customer
      description: >-
        Authenticates a customer (password login, OTP, social login) and returns
        an access token. Modeled from the SDK auth methods.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthInput'
      responses:
        '200':
          description: An access token and customer.
          content:
            application/json:
              schema:
                type: object
                properties:
                  accessToken:
                    type: string
                  customer:
                    $ref: '#/components/schemas/Customer'
  /customers/{id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      operationId: getCustomer
      tags:
        - Customers
      summary: Get a customer
      description: Retrieves a customer profile. Modeled from the SDK.
      responses:
        '200':
          description: The requested customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateCustomer
      tags:
        - Customers
      summary: Update a customer
      description: Updates a customer profile. Modeled from the SDK.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerInput'
      responses:
        '200':
          description: The updated customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
  /customers/{id}/addresses:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      operationId: listCustomerAddresses
      tags:
        - Customers
      summary: List customer addresses
      description: Lists a customer's saved addresses. Modeled from the SDK.
      responses:
        '200':
          description: A list of addresses.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Address'
    post:
      operationId: createCustomerAddress
      tags:
        - Customers
      summary: Create a customer address
      description: Adds a saved address to a customer. Modeled from the SDK.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Address'
      responses:
        '201':
          description: The created address.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Address'
  /customers/{id}/payment-methods:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      operationId: listCustomerPaymentMethods
      tags:
        - Customers
      summary: List customer payment methods
      description: Lists a customer's stored payment methods / wallet. Modeled from the SDK.
      responses:
        '200':
          description: A list of payment methods.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PaymentMethod'
  /subscriptions:
    get:
      operationId: listSubscriptions
      tags:
        - Subscriptions
      summary: List subscriptions
      description: Lists the authenticated customer's subscriptions. Modeled from the SDK.
      responses:
        '200':
          description: A list of subscriptions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Subscription'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /subscriptions/{id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      operationId: getSubscription
      tags:
        - Subscriptions
      summary: Get a subscription
      description: Loads a subscription by ID. Modeled from the SDK.
      responses:
        '200':
          description: The requested subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateSubscription
      tags:
        - Subscriptions
      summary: Update a subscription
      description: >-
        Updates a subscription, including bundle selections and survey /
        preference management. Modeled from the SDK.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionInput'
      responses:
        '200':
          description: The updated subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-Subbly-Api-Key
      description: >-
        Modeled. Subbly's storefront SDK is configured with an apiKey issued in
        the Subbly admin (Shop Settings). The exact header/parameter name is not
        published by Subbly.
  parameters:
    Id:
      name: id
      in: path
      required: true
      description: The resource identifier.
      schema:
        type: string
  responses:
    Unauthorized:
      description: Missing or invalid API key / access token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Product:
      type: object
      description: A storefront product or variant (modeled).
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
          description: For example one_time or subscription.
        price:
          type: integer
          description: Price in the smallest currency unit.
        currency:
          type: string
    Bundle:
      type: object
      description: A bundle product (modeled).
      properties:
        id:
          type: string
        name:
          type: string
        minItems:
          type: integer
        maxItems:
          type: integer
    BundleQuoteInput:
      type: object
      description: Selected items to quote for a bundle (modeled).
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              productId:
                type: string
              quantity:
                type: integer
    Quote:
      type: object
      description: A computed price quote (modeled).
      properties:
        total:
          type: integer
        currency:
          type: string
    Cart:
      type: object
      description: A shopping cart (modeled).
      properties:
        id:
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/CartItemInput'
        couponCode:
          type: string
        giftCardCode:
          type: string
        shippingMethodId:
          type: string
        total:
          type: integer
        currency:
          type: string
    CartInput:
      type: object
      description: Updatable cart fields (modeled).
      properties:
        couponCode:
          type: string
        giftCardCode:
          type: string
        shippingMethodId:
          type: string
        giftingDate:
          type: string
          format: date
    CartItemInput:
      type: object
      description: A cart line item (modeled).
      properties:
        productId:
          type: string
        quantity:
          type: integer
    CheckoutInput:
      type: object
      description: Checkout / purchase request (modeled).
      properties:
        cartId:
          type: string
        customerId:
          type: string
        paymentMethodId:
          type: string
    Order:
      type: object
      description: A resulting order / purchase (modeled).
      properties:
        id:
          type: string
        status:
          type: string
        total:
          type: integer
        currency:
          type: string
    Customer:
      type: object
      description: A customer account (modeled).
      properties:
        id:
          type: string
        email:
          type: string
        firstName:
          type: string
        lastName:
          type: string
    CustomerInput:
      type: object
      description: Customer create / update fields (modeled).
      properties:
        email:
          type: string
        password:
          type: string
        firstName:
          type: string
        lastName:
          type: string
    AuthInput:
      type: object
      description: Customer authentication request (modeled).
      properties:
        email:
          type: string
        password:
          type: string
        otp:
          type: string
        provider:
          type: string
          description: For social login, for example google or facebook.
    Address:
      type: object
      description: A customer address (modeled).
      properties:
        id:
          type: string
        line1:
          type: string
        line2:
          type: string
        city:
          type: string
        region:
          type: string
        postalCode:
          type: string
        country:
          type: string
    PaymentMethod:
      type: object
      description: A stored payment method / wallet entry (modeled).
      properties:
        id:
          type: string
        brand:
          type: string
        last4:
          type: string
        expMonth:
          type: integer
        expYear:
          type: integer
    Subscription:
      type: object
      description: A customer subscription (modeled).
      properties:
        id:
          type: string
        status:
          type: string
        productId:
          type: string
        nextBillingDate:
          type: string
          format: date
        interval:
          type: string
    SubscriptionInput:
      type: object
      description: Subscription update fields (modeled).
      properties:
        status:
          type: string
        bundleSelections:
          type: array
          items:
            type: object
            properties:
              productId:
                type: string
              quantity:
                type: integer
        surveyAnswers:
          type: object
          additionalProperties: true
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string