Swell Cart API

openapi: 3.2.0
info:
  title: Swell Frontend Cart API
  version: 2025-01
  description: Swell Frontend API — the client-safe, public-key-authenticated REST surface used from storefronts, single-page apps, and headless commerce experiences. Exposes a curated subset of the Backend API authorized with a public key plus a session token. Powers Swell.js, the React/Vue/Next storefront kits (Origin, Horizon, Verswell), and any custom JAMstack or SSR storefront. Resources include products, categories, carts, accounts, orders, subscriptions, payments, coupons, gift cards, store settings, currencies, localization, menus, and content pages.
  contact:
    name: Swell Developer Support
    url: https://developers.swell.is/frontend-api/introduction
  license:
    name: API Profile — API Evangelist
    url: https://apievangelist.com
servers:
- url: https://{storeId}.swell.store
  description: Per-store Frontend API endpoint
  variables:
    storeId:
      default: my-store
      description: Your Swell store ID (subdomain).
security:
- SwellPublicKey: []
tags:
- name: Cart
  description: Session-scoped shopping cart for the current visitor.
paths:
  /api/cart:
    get:
      tags:
      - Cart
      summary: Retrieve Current Cart
      operationId: frontendGetCart
      responses:
        '200':
          description: Current cart for the session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cart'
    put:
      tags:
      - Cart
      summary: Update Current Cart
      operationId: frontendUpdateCart
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Cart'
      responses:
        '200':
          description: Updated cart.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cart'
  /api/cart/items:
    post:
      tags:
      - Cart
      summary: Add Item To Cart
      operationId: frontendAddCartItem
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                product_id:
                  type: string
                quantity:
                  type: integer
                variant_id:
                  type: string
                options:
                  type: array
                  items:
                    type: object
      responses:
        '200':
          description: Updated cart.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cart'
  /api/cart/items/{itemId}:
    parameters:
    - name: itemId
      in: path
      required: true
      schema:
        type: string
    put:
      tags:
      - Cart
      summary: Update Cart Item
      operationId: frontendUpdateCartItem
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                quantity:
                  type: integer
      responses:
        '200':
          description: Updated.
    delete:
      tags:
      - Cart
      summary: Remove Cart Item
      operationId: frontendRemoveCartItem
      responses:
        '200':
          description: Removed.
  /api/cart/apply-coupon:
    put:
      tags:
      - Cart
      summary: Apply Coupon To Cart
      operationId: frontendApplyCoupon
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: string
      responses:
        '200':
          description: Coupon applied.
  /api/cart/apply-giftcard:
    put:
      tags:
      - Cart
      summary: Apply Gift Card To Cart
      operationId: frontendApplyGiftcard
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: string
      responses:
        '200':
          description: Gift card applied.
  /api/cart/recover/{token}:
    parameters:
    - name: token
      in: path
      required: true
      schema:
        type: string
    get:
      tags:
      - Cart
      summary: Recover Cart
      operationId: frontendRecoverCart
      responses:
        '200':
          description: Recovered cart.
components:
  schemas:
    Money:
      type: number
      format: float
    Cart:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
        account_id:
          type: string
        items:
          type: array
          items:
            type: object
        billing:
          type: object
        shipping:
          type: object
        sub_total:
          $ref: '#/components/schemas/Money'
        tax_total:
          $ref: '#/components/schemas/Money'
        discount_total:
          $ref: '#/components/schemas/Money'
        shipment_total:
          $ref: '#/components/schemas/Money'
        grand_total:
          $ref: '#/components/schemas/Money'
        coupon_code:
          type: string
        currency:
          type: string
  securitySchemes:
    SwellPublicKey:
      type: apiKey
      in: header
      name: Authorization
      description: 'Public storefront key, prefixed with `pk_`. Pass as `Authorization: pk_...`.'