openapi: 3.1.0
info:
  title: Swell Backend API
  description: >-
    Swell is a composable headless commerce platform exposing a server-side
    Backend API for managing products, orders, customers, and related resources.
    The HTTP API is organized around REST principles and is authenticated using
    your Store ID and a Secret Key issued from the Swell Developer dashboard.
    Note: Swell's official SDKs use a proprietary wire protocol on port 8443 for
    performance; this OpenAPI documents the HTTP-equivalent REST shape used by
    the Backend API.
  version: "1.0.0"
  contact:
    name: Swell developer documentation
    url: https://developers.swell.is/backend-api/introduction
servers:
  - url: https://api.swell.store
    description: Production
security:
  - basicAuth: []
tags:
  - name: Products
  - name: Orders
paths:
  /products:
    get:
      tags: [Products]
      summary: List products
      operationId: listProducts
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Where'
        - $ref: '#/components/parameters/Search'
        - $ref: '#/components/parameters/Sort'
      responses:
        '200':
          description: Paginated list of products
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductCollection'
    post:
      tags: [Products]
      summary: Create a product
      operationId: createProduct
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductInput'
      responses:
        '200':
          description: Created product
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
  /products/{id}:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/Expand'
      - $ref: '#/components/parameters/Fields'
    get:
      tags: [Products]
      summary: Retrieve a product
      operationId: getProduct
      responses:
        '200':
          description: Product
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
    put:
      tags: [Products]
      summary: Update a product
      operationId: updateProduct
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductInput'
      responses:
        '200':
          description: Updated product
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
    delete:
      tags: [Products]
      summary: Delete a product
      operationId: deleteProduct
      responses:
        '200':
          description: Deleted product
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
  /orders:
    get:
      tags: [Orders]
      summary: List orders
      operationId: listOrders
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Where'
        - $ref: '#/components/parameters/Sort'
      responses:
        '200':
          description: Paginated list of orders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderCollection'
    post:
      tags: [Orders]
      summary: Create an order
      operationId: createOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderInput'
      responses:
        '200':
          description: Created order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
  /orders/{id}:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/Expand'
      - $ref: '#/components/parameters/Fields'
    get:
      tags: [Orders]
      summary: Retrieve an order
      operationId: getOrder
      responses:
        '200':
          description: Order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
    put:
      tags: [Orders]
      summary: Update an order
      operationId: updateOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderInput'
      responses:
        '200':
          description: Updated order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
    delete:
      tags: [Orders]
      summary: Delete an order
      operationId: deleteOrder
      responses:
        '200':
          description: Deleted order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
components:
  parameters:
    Limit:
      in: query
      name: limit
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 15
      description: Records per page (1-1000, default 15).
    Page:
      in: query
      name: page
      schema:
        type: integer
        minimum: 1
    Where:
      in: query
      name: where
      schema:
        type: string
      description: JSON-encoded filter criteria.
    Search:
      in: query
      name: search
      schema:
        type: string
    Sort:
      in: query
      name: sort
      schema:
        type: string
    Expand:
      in: query
      name: expand
      schema:
        type: string
      description: Comma-separated related fields to include.
    Fields:
      in: query
      name: fields
      schema:
        type: string
      description: Comma-separated specific fields to return.
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic auth where the username is your Swell Store ID and the
        password is your Secret Key from the Developer dashboard.
  schemas:
    ProductInput:
      type: object
      required: [name]
      properties:
        name:
          type: string
        price:
          type: number
          format: float
        sku:
          type: string
        active:
          type: boolean
        purchase_options:
          type: object
          additionalProperties: true
        options:
          type: array
          items:
            type: object
            additionalProperties: true
        description:
          type: string
    Product:
      allOf:
        - $ref: '#/components/schemas/ProductInput'
        - type: object
          properties:
            id:
              type: string
            slug:
              type: string
            type:
              type: string
              enum: [standard, subscription, bundle, giftcard]
            delivery:
              type: string
              enum: [shipment, subscription, giftcard]
            date_created:
              type: string
              format: date-time
            date_updated:
              type: string
              format: date-time
    ProductCollection:
      type: object
      properties:
        count:
          type: integer
        results:
          type: array
          items:
            $ref: '#/components/schemas/Product'
        pages:
          type: object
          additionalProperties: true
    OrderInput:
      type: object
      required: [account_id, items]
      properties:
        account_id:
          type: string
        items:
          type: array
          items:
            type: object
            required: [product_id, quantity]
            properties:
              product_id:
                type: string
              quantity:
                type: integer
                minimum: 1
              price:
                type: number
                format: float
        billing:
          type: object
          additionalProperties: true
        shipping:
          type: object
          additionalProperties: true
        coupon_code:
          type: string
        comments:
          type: string
        gift:
          type: boolean
    Order:
      allOf:
        - $ref: '#/components/schemas/OrderInput'
        - type: object
          properties:
            id:
              type: string
            number:
              type: string
            status:
              type: string
              enum:
                - pending
                - draft
                - payment_pending
                - delivery_pending
                - hold
                - complete
                - canceled
            grand_total:
              type: number
              format: float
            payment_balance:
              type: number
              format: float
            date_created:
              type: string
              format: date-time
    OrderCollection:
      type: object
      properties:
        count:
          type: integer
        results:
          type: array
          items:
            $ref: '#/components/schemas/Order'
        pages:
          type: object
          additionalProperties: true