openapi: 3.0.3
info:
  title: Swell Backend API
  version: "2025-01"
  description: >-
    Swell Backend API — the server-side REST surface for managing every resource
    in a Swell commerce store: products, variants, carts, orders, payments,
    refunds, shipments, returns, subscriptions, accounts (customers),
    invoices, coupons, promotions, gift cards, content, files, data models,
    events, and webhooks. Authenticated with a store ID and secret key. The
    official Node and PHP libraries connect over a custom wire protocol on
    port 8443 for improved performance; HTTPS REST is available at
    https://api.swell.store.
  contact:
    name: Swell Developer Support
    url: https://developers.swell.is
    email: support@swell.is
  license:
    name: API Profile — API Evangelist
    url: https://apievangelist.com
servers:
  - url: https://api.swell.store
    description: Production Backend API
security:
  - SwellStoreId: []
    SwellSecretKey: []
tags:
  - name: Products
    description: Product catalog including variants, options, bundles, gift cards, and subscription products.
  - name: Variants
    description: Variant-level inventory and pricing under a parent product.
  - name: Stock
    description: Stock levels and stock adjustments across locations.
  - name: Categories
    description: Category tree and product taxonomy.
  - name: Attributes
    description: Product attributes used for filtering and faceted search.
  - name: Purchase Links
    description: Shareable purchase links that prefill a cart.
  - name: Carts
    description: Pending purchase requests that can be converted into orders.
  - name: Orders
    description: Customer orders, line items, financial totals, and lifecycle.
  - name: Payments
    description: Payment transactions, refunds, and gateway settlement.
  - name: Refunds
    description: Refund records linked to a payment.
  - name: Shipments
    description: Fulfillment shipments, tracking, and split fulfillment.
  - name: Returns
    description: Customer return merchandise authorizations.
  - name: Subscriptions
    description: Recurring billing subscriptions and plans.
  - name: Subscription Plans
    description: Plan templates that define billing schedule and price for recurring products.
  - name: Accounts
    description: Customer accounts including billing/shipping, saved cards, and history.
  - name: Account Addresses
    description: Saved shipping/billing addresses on an account.
  - name: Account Cards
    description: Saved payment cards on an account.
  - name: Account Credits
    description: Store credit balances and transactions per account.
  - name: Invoices
    description: Invoices generated for subscription billing cycles and B2B orders.
  - name: Coupons
    description: Coupon definitions with codes, redemptions, and discount rules.
  - name: Promotions
    description: Automatic promotion rules applied at cart and checkout.
  - name: Gift Cards
    description: Gift cards, debit transactions, and gift card products.
  - name: Content
    description: Pages, custom data models, and stored records.
  - name: Files
    description: Stored files (images, attachments) served via Swell CDN.
  - name: Events
    description: Event records emitted by the platform.
  - name: Webhooks
    description: Webhook subscriptions for receiving event callbacks.
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/Sort'
        - $ref: '#/components/parameters/Search'
        - $ref: '#/components/parameters/Expand'
        - $ref: '#/components/parameters/Fields'
      responses:
        '200':
          description: A page of products.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductList'
    post:
      tags: [Products]
      summary: Create Product
      operationId: createProduct
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductCreate'
      responses:
        '201':
          description: Product created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
  /products/{id}:
    parameters:
      - $ref: '#/components/parameters/PathId'
    get:
      tags: [Products]
      summary: Retrieve Product
      operationId: getProduct
      responses:
        '200':
          description: The requested product.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
    put:
      tags: [Products]
      summary: Update Product
      operationId: updateProduct
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductUpdate'
      responses:
        '200':
          description: Product updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
    delete:
      tags: [Products]
      summary: Delete Product
      operationId: deleteProduct
      responses:
        '200':
          description: Product deleted.
  /variants:
    get:
      tags: [Variants]
      summary: List Variants
      operationId: listVariants
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Where'
      responses:
        '200':
          description: A page of variants.
    post:
      tags: [Variants]
      summary: Create Variant
      operationId: createVariant
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Variant created.
  /variants/{id}:
    parameters:
      - $ref: '#/components/parameters/PathId'
    get:
      tags: [Variants]
      summary: Retrieve Variant
      operationId: getVariant
      responses:
        '200': { description: Variant. }
    put:
      tags: [Variants]
      summary: Update Variant
      operationId: updateVariant
      requestBody:
        required: true
        content: { application/json: { schema: { type: object } } }
      responses:
        '200': { description: Updated. }
    delete:
      tags: [Variants]
      summary: Delete Variant
      operationId: deleteVariant
      responses:
        '200': { description: Deleted. }
  /stock:
    get:
      tags: [Stock]
      summary: List Stock Entries
      operationId: listStock
      responses:
        '200': { description: Stock entries. }
    post:
      tags: [Stock]
      summary: Adjust Stock
      operationId: adjustStock
      requestBody:
        required: true
        content: { application/json: { schema: { type: object } } }
      responses:
        '201': { description: Stock adjustment created. }
  /categories:
    get:
      tags: [Categories]
      summary: List Categories
      operationId: listCategories
      responses:
        '200': { description: Categories. }
    post:
      tags: [Categories]
      summary: Create Category
      operationId: createCategory
      requestBody:
        required: true
        content: { application/json: { schema: { type: object } } }
      responses:
        '201': { description: Created. }
  /categories/{id}:
    parameters: [ { $ref: '#/components/parameters/PathId' } ]
    get:
      tags: [Categories]
      summary: Retrieve Category
      operationId: getCategory
      responses: { '200': { description: Category. } }
    put:
      tags: [Categories]
      summary: Update Category
      operationId: updateCategory
      requestBody: { required: true, content: { application/json: { schema: { type: object } } } }
      responses: { '200': { description: Updated. } }
    delete:
      tags: [Categories]
      summary: Delete Category
      operationId: deleteCategory
      responses: { '200': { description: Deleted. } }
  /attributes:
    get:
      tags: [Attributes]
      summary: List Attributes
      operationId: listAttributes
      responses: { '200': { description: Attributes. } }
    post:
      tags: [Attributes]
      summary: Create Attribute
      operationId: createAttribute
      requestBody: { required: true, content: { application/json: { schema: { type: object } } } }
      responses: { '201': { description: Created. } }
  /purchase-links:
    get:
      tags: [Purchase Links]
      summary: List Purchase Links
      operationId: listPurchaseLinks
      responses: { '200': { description: Purchase links. } }
    post:
      tags: [Purchase Links]
      summary: Create Purchase Link
      operationId: createPurchaseLink
      requestBody: { required: true, content: { application/json: { schema: { type: object } } } }
      responses: { '201': { description: Created. } }
  /carts:
    get:
      tags: [Carts]
      summary: List Carts
      operationId: listCarts
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Where'
      responses:
        '200':
          description: A page of carts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartList'
    post:
      tags: [Carts]
      summary: Create Cart
      operationId: createCart
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CartCreate'
      responses:
        '201':
          description: Cart created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cart'
  /carts/{id}:
    parameters: [ { $ref: '#/components/parameters/PathId' } ]
    get:
      tags: [Carts]
      summary: Retrieve Cart
      operationId: getCart
      responses:
        '200':
          description: Cart.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cart'
    put:
      tags: [Carts]
      summary: Update Cart
      operationId: updateCart
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CartUpdate'
      responses:
        '200':
          description: Updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cart'
    delete:
      tags: [Carts]
      summary: Delete Cart
      operationId: deleteCart
      responses: { '200': { description: Deleted. } }
  /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'
        - $ref: '#/components/parameters/Expand'
      responses:
        '200':
          description: A page of orders.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderList'
    post:
      tags: [Orders]
      summary: Create Order
      operationId: createOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderCreate'
      responses:
        '201':
          description: Order created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
  /orders/{id}:
    parameters: [ { $ref: '#/components/parameters/PathId' } ]
    get:
      tags: [Orders]
      summary: Retrieve Order
      operationId: getOrder
      responses:
        '200':
          description: Order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
    patch:
      tags: [Orders]
      summary: Update Order
      operationId: updateOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderUpdate'
      responses:
        '200':
          description: Updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
    delete:
      tags: [Orders]
      summary: Delete Order
      operationId: deleteOrder
      responses: { '200': { description: Deleted. } }
  /payments:
    get:
      tags: [Payments]
      summary: List Payments
      operationId: listPayments
      responses:
        '200':
          description: A page of payments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentList'
    post:
      tags: [Payments]
      summary: Create Payment
      operationId: createPayment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentCreate'
      responses:
        '201':
          description: Payment created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
  /payments/{id}:
    parameters: [ { $ref: '#/components/parameters/PathId' } ]
    get:
      tags: [Payments]
      summary: Retrieve Payment
      operationId: getPayment
      responses:
        '200': { description: Payment. }
    put:
      tags: [Payments]
      summary: Update Payment
      operationId: updatePayment
      requestBody: { required: true, content: { application/json: { schema: { type: object } } } }
      responses: { '200': { description: Updated. } }
  /payments/{id}/refunds:
    parameters: [ { $ref: '#/components/parameters/PathId' } ]
    post:
      tags: [Refunds]
      summary: Refund Payment
      operationId: refundPayment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundCreate'
      responses:
        '201':
          description: Refund created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
  /refunds:
    get:
      tags: [Refunds]
      summary: List Refunds
      operationId: listRefunds
      responses: { '200': { description: Refunds. } }
  /shipments:
    get:
      tags: [Shipments]
      summary: List Shipments
      operationId: listShipments
      responses: { '200': { description: Shipments. } }
    post:
      tags: [Shipments]
      summary: Create Shipment
      operationId: createShipment
      requestBody: { required: true, content: { application/json: { schema: { type: object } } } }
      responses: { '201': { description: Created. } }
  /shipments/{id}:
    parameters: [ { $ref: '#/components/parameters/PathId' } ]
    get:
      tags: [Shipments]
      summary: Retrieve Shipment
      operationId: getShipment
      responses: { '200': { description: Shipment. } }
    put:
      tags: [Shipments]
      summary: Update Shipment
      operationId: updateShipment
      requestBody: { required: true, content: { application/json: { schema: { type: object } } } }
      responses: { '200': { description: Updated. } }
  /returns:
    get:
      tags: [Returns]
      summary: List Returns
      operationId: listReturns
      responses: { '200': { description: Returns. } }
    post:
      tags: [Returns]
      summary: Create Return
      operationId: createReturn
      requestBody: { required: true, content: { application/json: { schema: { type: object } } } }
      responses: { '201': { description: Created. } }
  /returns/{id}:
    parameters: [ { $ref: '#/components/parameters/PathId' } ]
    get:
      tags: [Returns]
      summary: Retrieve Return
      operationId: getReturn
      responses: { '200': { description: Return. } }
    put:
      tags: [Returns]
      summary: Update Return
      operationId: updateReturn
      requestBody: { required: true, content: { application/json: { schema: { type: object } } } }
      responses: { '200': { description: Updated. } }
  /subscriptions:
    get:
      tags: [Subscriptions]
      summary: List Subscriptions
      operationId: listSubscriptions
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Where'
      responses:
        '200':
          description: A page of subscriptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionList'
    post:
      tags: [Subscriptions]
      summary: Create Subscription
      operationId: createSubscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionCreate'
      responses:
        '201':
          description: Subscription created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
  /subscriptions/{id}:
    parameters: [ { $ref: '#/components/parameters/PathId' } ]
    get:
      tags: [Subscriptions]
      summary: Retrieve Subscription
      operationId: getSubscription
      responses:
        '200':
          description: Subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
    put:
      tags: [Subscriptions]
      summary: Update Subscription
      operationId: updateSubscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionUpdate'
      responses:
        '200':
          description: Updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
    delete:
      tags: [Subscriptions]
      summary: Cancel Subscription
      operationId: cancelSubscription
      responses: { '200': { description: Subscription canceled. } }
  /subscription-plans:
    get:
      tags: [Subscription Plans]
      summary: List Subscription Plans
      operationId: listSubscriptionPlans
      responses: { '200': { description: Plans. } }
    post:
      tags: [Subscription Plans]
      summary: Create Subscription Plan
      operationId: createSubscriptionPlan
      requestBody: { required: true, content: { application/json: { schema: { type: object } } } }
      responses: { '201': { description: Created. } }
  /accounts:
    get:
      tags: [Accounts]
      summary: List Accounts
      operationId: listAccounts
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Where'
      responses:
        '200':
          description: A page of accounts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountList'
    post:
      tags: [Accounts]
      summary: Create Account
      operationId: createAccount
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountCreate'
      responses:
        '201':
          description: Account created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
  /accounts/{id}:
    parameters: [ { $ref: '#/components/parameters/PathId' } ]
    get:
      tags: [Accounts]
      summary: Retrieve Account
      operationId: getAccount
      responses:
        '200':
          description: Account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
    put:
      tags: [Accounts]
      summary: Update Account
      operationId: updateAccount
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountUpdate'
      responses:
        '200':
          description: Updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
    delete:
      tags: [Accounts]
      summary: Delete Account
      operationId: deleteAccount
      responses: { '200': { description: Deleted. } }
  /accounts/{id}/addresses:
    parameters: [ { $ref: '#/components/parameters/PathId' } ]
    get:
      tags: [Account Addresses]
      summary: List Account Addresses
      operationId: listAccountAddresses
      responses: { '200': { description: Addresses. } }
    post:
      tags: [Account Addresses]
      summary: Create Account Address
      operationId: createAccountAddress
      requestBody: { required: true, content: { application/json: { schema: { type: object } } } }
      responses: { '201': { description: Created. } }
  /accounts/{id}/cards:
    parameters: [ { $ref: '#/components/parameters/PathId' } ]
    get:
      tags: [Account Cards]
      summary: List Account Cards
      operationId: listAccountCards
      responses: { '200': { description: Cards. } }
    post:
      tags: [Account Cards]
      summary: Tokenize Account Card
      operationId: createAccountCard
      requestBody: { required: true, content: { application/json: { schema: { type: object } } } }
      responses: { '201': { description: Created. } }
  /accounts/{id}/credits:
    parameters: [ { $ref: '#/components/parameters/PathId' } ]
    get:
      tags: [Account Credits]
      summary: List Account Credits
      operationId: listAccountCredits
      responses: { '200': { description: Credits. } }
    post:
      tags: [Account Credits]
      summary: Adjust Account Credit
      operationId: createAccountCredit
      requestBody: { required: true, content: { application/json: { schema: { type: object } } } }
      responses: { '201': { description: Created. } }
  /invoices:
    get:
      tags: [Invoices]
      summary: List Invoices
      operationId: listInvoices
      responses: { '200': { description: Invoices. } }
    post:
      tags: [Invoices]
      summary: Create Invoice
      operationId: createInvoice
      requestBody: { required: true, content: { application/json: { schema: { type: object } } } }
      responses: { '201': { description: Created. } }
  /invoices/{id}:
    parameters: [ { $ref: '#/components/parameters/PathId' } ]
    get:
      tags: [Invoices]
      summary: Retrieve Invoice
      operationId: getInvoice
      responses: { '200': { description: Invoice. } }
    put:
      tags: [Invoices]
      summary: Update Invoice
      operationId: updateInvoice
      requestBody: { required: true, content: { application/json: { schema: { type: object } } } }
      responses: { '200': { description: Updated. } }
  /coupons:
    get:
      tags: [Coupons]
      summary: List Coupons
      operationId: listCoupons
      responses: { '200': { description: Coupons. } }
    post:
      tags: [Coupons]
      summary: Create Coupon
      operationId: createCoupon
      requestBody: { required: true, content: { application/json: { schema: { type: object } } } }
      responses: { '201': { description: Created. } }
  /coupons/{id}:
    parameters: [ { $ref: '#/components/parameters/PathId' } ]
    get:
      tags: [Coupons]
      summary: Retrieve Coupon
      operationId: getCoupon
      responses: { '200': { description: Coupon. } }
    put:
      tags: [Coupons]
      summary: Update Coupon
      operationId: updateCoupon
      requestBody: { required: true, content: { application/json: { schema: { type: object } } } }
      responses: { '200': { description: Updated. } }
    delete:
      tags: [Coupons]
      summary: Delete Coupon
      operationId: deleteCoupon
      responses: { '200': { description: Deleted. } }
  /promotions:
    get:
      tags: [Promotions]
      summary: List Promotions
      operationId: listPromotions
      responses: { '200': { description: Promotions. } }
    post:
      tags: [Promotions]
      summary: Create Promotion
      operationId: createPromotion
      requestBody: { required: true, content: { application/json: { schema: { type: object } } } }
      responses: { '201': { description: Created. } }
  /promotions/{id}:
    parameters: [ { $ref: '#/components/parameters/PathId' } ]
    get:
      tags: [Promotions]
      summary: Retrieve Promotion
      operationId: getPromotion
      responses: { '200': { description: Promotion. } }
    put:
      tags: [Promotions]
      summary: Update Promotion
      operationId: updatePromotion
      requestBody: { required: true, content: { application/json: { schema: { type: object } } } }
      responses: { '200': { description: Updated. } }
    delete:
      tags: [Promotions]
      summary: Delete Promotion
      operationId: deletePromotion
      responses: { '200': { description: Deleted. } }
  /giftcards:
    get:
      tags: [Gift Cards]
      summary: List Gift Cards
      operationId: listGiftcards
      responses: { '200': { description: Gift cards. } }
    post:
      tags: [Gift Cards]
      summary: Create Gift Card
      operationId: createGiftcard
      requestBody: { required: true, content: { application/json: { schema: { type: object } } } }
      responses: { '201': { description: Created. } }
  /giftcards/{id}:
    parameters: [ { $ref: '#/components/parameters/PathId' } ]
    get:
      tags: [Gift Cards]
      summary: Retrieve Gift Card
      operationId: getGiftcard
      responses: { '200': { description: Gift card. } }
    put:
      tags: [Gift Cards]
      summary: Update Gift Card
      operationId: updateGiftcard
      requestBody: { required: true, content: { application/json: { schema: { type: object } } } }
      responses: { '200': { description: Updated. } }
  /pages:
    get:
      tags: [Content]
      summary: List Content Pages
      operationId: listPages
      responses: { '200': { description: Pages. } }
    post:
      tags: [Content]
      summary: Create Content Page
      operationId: createPage
      requestBody: { required: true, content: { application/json: { schema: { type: object } } } }
      responses: { '201': { description: Created. } }
  /pages/{id}:
    parameters: [ { $ref: '#/components/parameters/PathId' } ]
    get:
      tags: [Content]
      summary: Retrieve Content Page
      operationId: getPage
      responses: { '200': { description: Page. } }
    put:
      tags: [Content]
      summary: Update Content Page
      operationId: updatePage
      requestBody: { required: true, content: { application/json: { schema: { type: object } } } }
      responses: { '200': { description: Updated. } }
    delete:
      tags: [Content]
      summary: Delete Content Page
      operationId: deletePage
      responses: { '200': { description: Deleted. } }
  /files:
    get:
      tags: [Files]
      summary: List Files
      operationId: listFiles
      responses: { '200': { description: Files. } }
    post:
      tags: [Files]
      summary: Upload File
      operationId: uploadFile
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses: { '201': { description: File uploaded. } }
  /events:
    get:
      tags: [Events]
      summary: List Events
      operationId: listEvents
      responses: { '200': { description: Events. } }
  /webhooks:
    get:
      tags: [Webhooks]
      summary: List Webhook Subscriptions
      operationId: listWebhooks
      responses:
        '200':
          description: Webhook subscriptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookList'
    post:
      tags: [Webhooks]
      summary: Create Webhook Subscription
      operationId: createWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreate'
      responses:
        '201':
          description: Webhook subscription created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
  /webhooks/{id}:
    parameters: [ { $ref: '#/components/parameters/PathId' } ]
    get:
      tags: [Webhooks]
      summary: Retrieve Webhook Subscription
      operationId: getWebhook
      responses:
        '200':
          description: Webhook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
    put:
      tags: [Webhooks]
      summary: Update Webhook Subscription
      operationId: updateWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookUpdate'
      responses:
        '200':
          description: Updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
    delete:
      tags: [Webhooks]
      summary: Delete Webhook Subscription
      operationId: deleteWebhook
      responses: { '200': { description: Deleted. } }
components:
  securitySchemes:
    SwellStoreId:
      type: apiKey
      in: header
      name: X-Store-Id
      description: Your Swell store ID, found in the Developer section of the dashboard.
    SwellSecretKey:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Secret API key prefixed with `sk_`. Sent as `Authorization: Basic <base64(store-id:secret-key)>` or
        equivalent custom header by official libraries.
  parameters:
    PathId:
      name: id
      in: path
      required: true
      description: The object ID of the resource.
      schema:
        type: string
        pattern: "^[a-f0-9]{24}$"
    Limit:
      name: limit
      in: query
      description: Records per page (1-1000). Default 15.
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 15
    Page:
      name: page
      in: query
      description: Result page number, 1-indexed.
      schema:
        type: integer
        minimum: 1
        default: 1
    Where:
      name: where
      in: query
      description: MongoDB-style filter object. Supports operators $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $regex, $type, $exists, $and, $or, $nor, $all, $elemMatch, $size.
      schema:
        type: object
    Sort:
      name: sort
      in: query
      description: 'Sort expression, e.g. "name asc" or "date_created desc".'
      schema:
        type: string
    Search:
      name: search
      in: query
      description: Full-text search across model-specific searchable fields.
      schema:
        type: string
    Expand:
      name: expand
      in: query
      description: 'Include related objects, e.g. expand=account or expand=variants:10.'
      schema:
        type: string
    Fields:
      name: fields
      in: query
      description: Comma-separated list of fields to return.
      schema:
        type: string
  schemas:
    Pagination:
      type: object
      properties:
        count:
          type: integer
        page:
          type: integer
        pages:
          type: object
    Money:
      type: number
      format: float
      description: Currency amount expressed in store currency.
    ObjectId:
      type: string
      pattern: "^[a-f0-9]{24}$"
    Product:
      type: object
      properties:
        id: { $ref: '#/components/schemas/ObjectId' }
        name: { type: string }
        slug: { type: string }
        sku: { type: string }
        active: { type: boolean }
        type:
          type: string
          enum: [standard, subscription, bundle, giftcard]
        delivery:
          type: string
          enum: [shipment, subscription, giftcard, null]
          nullable: true
        price: { $ref: '#/components/schemas/Money' }
        sale_price: { $ref: '#/components/schemas/Money' }
        sale: { type: boolean }
        currency: { type: string, description: 'ISO 4217 currency code.' }
        description: { type: string }
        stock_tracking: { type: boolean }
        stock_level: { type: integer }
        stock_status:
          type: string
          enum: [in_stock, out_of_stock, preorder, backorder]
        stock_purchasable: { type: boolean }
        variable: { type: boolean }
        variants: { type: array, items: { type: object } }
        options: { type: array, items: { type: object } }
        bundle: { type: boolean }
        bundle_items: { type: array, items: { type: object } }
        purchase_options: { type: object }
        category_id: { $ref: '#/components/schemas/ObjectId' }
        categories: { type: array, items: { type: object } }
        related_product_ids: { type: array, items: { $ref: '#/components/schemas/ObjectId' } }
        cross_sells: { type: array, items: { type: object } }
        up_sells: { type: array, items: { type: object } }
        shipment_weight: { type: number }
        shipment_dimensions: { type: object }
        shipment_location: { type: string }
        shipment_prices: { type: array, items: { type: object } }
        images: { type: array, items: { type: object } }
        tags: { type: array, items: { type: string } }
        meta_title: { type: string }
        meta_keywords: { type: string }
        meta_description: { type: string }
        date_created: { type: string, format: date-time }
        date_updated: { type: string, format: date-time }
      required: [name, sku]
    ProductCreate:
      allOf:
        - $ref: '#/components/schemas/Product'
    ProductUpdate:
      allOf:
        - $ref: '#/components/schemas/Product'
    ProductList:
      type: object
      properties:
        count: { type: integer }
        page: { type: integer }
        results:
          type: array
          items:
            $ref: '#/components/schemas/Product'
        pages: { type: object }
    Cart:
      type: object
      properties:
        id: { $ref: '#/components/schemas/ObjectId' }
        status:
          type: string
          enum: [active, converted, abandoned, recovered]
        account_id: { $ref: '#/components/schemas/ObjectId' }
        items: { type: array, items: { type: object } }
        billing: { type: object }
        shipping: { type: object }
        sub_total: { $ref: '#/components/schemas/Money' }
        discount_total: { $ref: '#/components/schemas/Money' }
        tax_total: { $ref: '#/components/schemas/Money' }
        shipment_total: { $ref: '#/components/schemas/Money' }
        grand_total: { $ref: '#/components/schemas/Money' }
        coupon_code: { type: string }
        currency: { type: string }
        date_created: { type: string, format: date-time }
        date_updated: { type: string, format: date-time }
    CartCreate: { $ref: '#/components/schemas/Cart' }
    CartUpdate: { $ref: '#/components/schemas/Cart' }
    CartList:
      type: object
      properties:
        count: { type: integer }
        page: { type: integer }
        results: { type: array, items: { $ref: '#/components/schemas/Cart' } }
    Order:
      type: object
      properties:
        id: { $ref: '#/components/schemas/ObjectId' }
        number: { type: string }
        account_id: { $ref: '#/components/schemas/ObjectId' }
        status:
          type: string
          enum: [pending, draft, payment_pending, delivery_pending, hold, complete, canceled]
        items: { type: array, items: { type: object } }
        billing: { type: object }
        shipping: { type: object }
        sub_total: { $ref: '#/components/schemas/Money' }
        discount_total: { $ref: '#/components/schemas/Money' }
        tax_total: { $ref: '#/components/schemas/Money' }
        shipment_total: { $ref: '#/components/schemas/Money' }
        grand_total: { $ref: '#/components/schemas/Money' }
        payment_balance: { $ref: '#/components/schemas/Money' }
        paid: { type: boolean }
        delivered: { type: boolean }
        refunded: { type: boolean }
        canceled: { type: boolean }
        coupon_code: { type: string }
        giftcards: { type: array, items: { type: object } }
        comments: { type: string }
        metadata: { type: object }
        test: { type: boolean }
        currency: { type: string }
        date_created: { type: string, format: date-time }
        date_updated: { type: string, format: date-time }
    OrderCreate: { $ref: '#/components/schemas/Order' }
    OrderUpdate: { $ref: '#/components/schemas/Order' }
    OrderList:
      type: object
      properties:
        count: { type: integer }
        page: { type: integer }
        results: { type: array, items: { $ref: '#/components/schemas/Order' } }
    Payment:
      type: object
      properties:
        id: { $ref: '#/components/schemas/ObjectId' }
        number: { type: string }
        account_id: { $ref: '#/components/schemas/ObjectId' }
        order_id: { $ref: '#/components/schemas/ObjectId' }
        amount: { $ref: '#/components/schemas/Money' }
        amount_refundable: { $ref: '#/components/schemas/Money' }
        amount_refunded: { $ref: '#/components/schemas/Money' }
        method:
          type: string
          enum: [card, account, amazon, paypal, manual]
        gateway: { type: string }
        status:
          type: string
          enum: [pending, error, success, authorized]
        transaction_id: { type: string }
        currency: { type: string }
        date_created: { type: string, format: date-time }
        date_updated: { type: string, format: date-time }
    PaymentCreate: { $ref: '#/components/schemas/Payment' }
    PaymentList:
      type: object
      properties:
        count: { type: integer }
        page: { type: integer }
        results: { type: array, items: { $ref: '#/components/schemas/Payment' } }
    Refund:
      type: object
      properties:
        id: { $ref: '#/components/schemas/ObjectId' }
        payment_id: { $ref: '#/components/schemas/ObjectId' }
        amount: { $ref: '#/components/schemas/Money' }
        reason: { type: string }
        date_created: { type: string, format: date-time }
    RefundCreate: { $ref: '#/components/schemas/Refund' }
    Subscription:
      type: object
      properties:
        id: { $ref: '#/components/schemas/ObjectId' }
        number: { type: string }
        account_id: { $ref: '#/components/schemas/ObjectId' }
        product_id: { $ref: '#/components/schemas/ObjectId' }
        plan_id: { $ref: '#/components/schemas/ObjectId' }
        status:
          type: string
          enum: [active, paid, unpaid, canceled, trial, pastdue, complete, paused]
        interval: { type: string, enum: [daily, weekly, monthly, yearly] }
        interval_count: { type: integer }
        trial_days: { type: integer }
        price: { $ref: '#/components/schemas/Money' }
        recurring_total: { $ref: '#/components/schemas/Money' }
        date_period_start: { type: string, format: date-time }
        date_period_end: { type: string, format: date-time }
        date_canceled: { type: string, format: date-time }
        date_created: { type: string, format: date-time }
        date_updated: { type: string, format: date-time }
    SubscriptionCreate: { $ref: '#/components/schemas/Subscription' }
    SubscriptionUpdate: { $ref: '#/components/schemas/Subscription' }
    SubscriptionList:
      type: object
      properties:
        count: { type: integer }
        page: { type: integer }
        results: { type: array, items: { $ref: '#/components/schemas/Subscription' } }
    Account:
      type: object
      properties:
        id: { $ref: '#/components/schemas/ObjectId' }
        email: { type: string, format: email }
        name: { type: string }
        first_name: { type: string }
        last_name: { type: string }
        phone: { type: string }
        type: { type: string, enum: [individual, business] }
        currency: { type: string }
        group: { type: string }
        balance: { $ref: '#/components/schemas/Money' }
        billing: { type: object }
        shipping: { type: object }
        order_count: { type: integer }
        order_value: { $ref: '#/components/schemas/Money' }
        cart_abandoned_count: { type: integer }
        email_optin: { type: boolean }
        date_first_order: { type: string, format: date-time }
        date_last_order: { type: string, format: date-time }
        date_last_login: { type: string, format: date-time }
        date_created: { type: string, format: date-time }
        date_updated: { type: string, format: date-time }
      required: [email]
    AccountCreate: { $ref: '#/components/schemas/Account' }
    AccountUpdate: { $ref: '#/components/schemas/Account' }
    AccountList:
      type: object
      properties:
        count: { type: integer }
        page: { type: integer }
        results: { type: array, items: { $ref: '#/components/schemas/Account' } }
    Webhook:
      type: object
      properties:
        id: { $ref: '#/components/schemas/ObjectId' }
        url: { type: string, format: uri }
        events: { type: array, items: { type: string } }
        enabled: { type: boolean }
        auto_disabled: { type: boolean }
        schedule: { type: object }
        date_created: { type: string, format: date-time }
        date_updated: { type: string, format: date-time }
      required: [url, events]
    WebhookCreate: { $ref: '#/components/schemas/Webhook' }
    WebhookUpdate: { $ref: '#/components/schemas/Webhook' }
    WebhookList:
      type: object
      properties:
        count: { type: integer }
        page: { type: integer }
        results: { type: array, items: { $ref: '#/components/schemas/Webhook' } }
    Error:
      type: object
      properties:
        errors:
          type: object
          additionalProperties:
            type: object
            properties:
              code: { type: string }
              message: { type: string }
              params: { type: object }