Swell

aid: swell-io
name: Swell
description: >-
  Swell is a customizable, API-first headless commerce platform powering modern B2C, B2B, subscription, and marketplace
  experiences. It exposes a server-side Backend API for managing the full commerce data model (products, variants,
  carts, orders, payments, refunds, shipments, returns, subscriptions, accounts, invoices, coupons, promotions, gift
  cards, content, files, events, webhooks) plus a public-key client-side Frontend API for storefronts and an
  experimental GraphQL endpoint. The platform ships official Node and PHP libraries, a universal JavaScript SDK
  (Swell.js), headless storefront starters for Next.js (Horizon, verswell-commerce, nextjs-commerce) and Nuxt (Origin),
  a Swell Apps platform with CLI and Apps SDK for extending the data and logic layers via custom data models, events,
  notifications, webhooks, and edge functions running in 200+ locations, plus AI coding-agent skills and Claude Code
  plugins.
url: https://raw.githubusercontent.com/api-evangelist/swell-io/refs/heads/main/apis.yml
created: '2026-05-25'
modified: '2026-05-25'
specificationVersion: '0.20'
tags:
- Commerce
- Headless Commerce
- API-First
- B2C
- B2B
- Subscriptions
- Marketplaces
- Wholesale
- Storefront
- Checkout
- Payments
- Carts
- Orders
- Catalog
- Internationalization
apis:
- aid: swell-io:swell-backend-api
  name: Swell Backend API
  tags:
  - Commerce
  - Backend
  - REST
  - Catalog
  - Orders
  - Payments
  - Subscriptions
  humanURL: https://developers.swell.is/backend-api/introduction
  baseURL: https://api.swell.store
  properties:
  - url: https://developers.swell.is/backend-api/introduction
    type: Documentation
  - url: https://developers.swell.is/backend-api/authentication
    type: Authentication
  - url: https://developers.swell.is/backend-api/querying
    type: APIReference
  - url: https://developers.swell.is/backend-api/errors
    type: APIReference
    name: Errors and Error Codes
  - url: openapi/swell-backend-api-openapi.yml
    type: OpenAPI
  - url: json-schema/swell-product-schema.json
    type: JSONSchema
  - url: json-schema/swell-order-schema.json
    type: JSONSchema
  - url: json-schema/swell-cart-schema.json
    type: JSONSchema
  - url: json-schema/swell-subscription-schema.json
    type: JSONSchema
  - url: json-schema/swell-account-schema.json
    type: JSONSchema
  - url: json-schema/swell-payment-schema.json
    type: JSONSchema
  - url: json-schema/swell-webhook-schema.json
    type: JSONSchema
  - url: json-structure/swell-product-structure.json
    type: JSONStructure
  - url: json-structure/swell-order-structure.json
    type: JSONStructure
  - url: json-structure/swell-subscription-structure.json
    type: JSONStructure
  - url: json-structure/swell-account-structure.json
    type: JSONStructure
  - url: examples/swell-product-create-example.json
    type: Example
  - url: examples/swell-order-create-example.json
    type: Example
  - url: examples/swell-subscription-create-example.json
    type: Example
  - url: examples/swell-account-create-example.json
    type: Example
  - url: examples/swell-webhook-event-example.json
    type: Example
  description: >-
    Server-side REST API authorized with a secret API key and store ID. Covers products, variants, stock, categories,
    attributes, purchase links, carts, orders, payments, refunds, shipments, returns, subscriptions, subscription
    plans, accounts, addresses, cards, credits, invoices, coupons, promotions, gift cards, content pages, files,
    events, and webhooks. Supports MongoDB-style `where` filters with operators ($eq, $ne, $gt, $gte, $lt, $lte, $in,
    $nin, $regex, $type, $exists, $and, $or, $nor, $all, $elemMatch, $size), `sort`, `limit` (1-1000, default 15),
    `page`, `search`, `expand`, `fields`, and `include`. Official libraries connect over a custom wire protocol on
    port 8443 for improved performance and caching; HTTPS REST is available at api.swell.store.
- aid: swell-io:swell-frontend-api
  name: Swell Frontend API
  tags:
  - Commerce
  - Frontend
  - Storefront
  - REST
  - JAMstack
  humanURL: https://developers.swell.is/frontend-api/introduction
  baseURL: https://{store-id}.swell.store
  properties:
  - url: https://developers.swell.is/frontend-api/introduction
    type: Documentation
  - url: openapi/swell-frontend-api-openapi.yml
    type: OpenAPI
  - url: examples/swell-cart-add-item-example.json
    type: Example
  description: >-
    Public-key-authorized REST API designed for storefronts, JAMstack apps, and SSR frameworks. Powers Swell.js and
    the official Next.js (Horizon, verswell-commerce, nextjs-commerce, nextjs-builder) and Nuxt (Origin) headless
    starters. Exposes products, categories, attributes, carts (with coupon and gift-card application, recovery, and
    order submission), authenticated customer accounts (login, recovery, addresses, cards, orders, subscriptions),
    store settings, payment settings, currencies, menus, and content models. Authenticated with a public key (pk_...)
    and a session token making it safe to use from any client context.
- aid: swell-io:swell-graphql-api
  name: Swell GraphQL API
  tags:
  - Commerce
  - GraphQL
  - Storefront
  - Experimental
  humanURL: https://developers.swell.is/frontend-api/frontend-libraries/graphql
  baseURL: https://{store-id}.swell.store/graphql/v2
  properties:
  - url: https://developers.swell.is/frontend-api/frontend-libraries/graphql
    type: Documentation
  - url: https://{store-id}.swell.store/playground
    type: APIReference
    name: GraphQL Playground
  - url: graphql/swell-io-graphql.md
    type: GraphQL
  description: >-
    Experimental (alpha) GraphQL endpoint that exposes a curated subset of the storefront commerce model — products,
    attributes, categories, accounts, sessions, carts, orders, payments, payment settings, subscriptions, store
    settings, currencies, and navigation menus. Authorized with a public storefront key passed in the Authorization
    header. Notable limits: no nested queries, no payment tokenization, no abandoned-cart recovery, no guest cart
    email updates. A GraphQL playground is available at /playground when logged into the dashboard.
- aid: swell-io:swell-webhooks-api
  name: Swell Webhooks
  tags:
  - Commerce
  - Eventing
  - Webhooks
  humanURL: https://developers.swell.is/backend-api/webhooks
  properties:
  - url: https://developers.swell.is/backend-api/webhooks
    type: Documentation
  - url: examples/swell-webhook-event-example.json
    type: Example
  description: >-
    Event-driven HTTP callbacks for cart, order, subscription, payment, account, and product lifecycle events.
    Configurable via the dashboard (Developer → Webhooks) or programmatically through the Backend API and Swell Apps.
    Payloads are JSON POSTs with `id`, `date_created`, `model`, `type`, and `data`. Endpoints must return 2xx; failed
    deliveries retry hourly for two days, continue hourly after, and auto-disable after three days. Webhooks originate
    from the documented Swell IP allowlist (52.52.111.237, 54.219.85.17, 54.241.235.166, plus 216.218.185.0/27,
    216.218.244.192/27, 74.80.234.0/24).
- aid: swell-io:swell-apps-platform
  name: Swell Apps Platform
  tags:
  - Apps
  - Extensions
  - Functions
  - Edge
  humanURL: https://developers.swell.is/apps/overview
  properties:
  - url: https://developers.swell.is/apps/overview
    type: Documentation
  - url: https://github.com/swellstores/apps-sdk
    type: SDK
    name: Swell Apps SDK
  - url: https://github.com/swellstores/app-types
    type: SDK
    name: Swell Apps TypeScript Bindings
  description: >-
    Swell Apps extend the platform with custom data models (added fields or new entities), events (triggering
    functions, webhooks, and notifications), edge functions deployed to 200+ locations with no cold start, and admin
    UI surfaces (settings, content views). Apps are distributed via a swell.json manifest and built with the Swell CLI
    and Apps SDK; TypeScript bindings are published in the app-types package. Used for first-party integrations
    (Contentful, Builder.io, honest reviews) and third-party merchant extensions.
maintainers:
- FN: Kin Lane
  email: kin@apievangelist.com
  url: https://kinlane.com
common:
- type: PostmanWorkspace
  url: https://www.postman.com/kinlaneapi/swell/overview
- type: ArazzoWorkflows
  url: arazzo/
  workflows:
  - url: arazzo/swell-io-apply-coupon-to-cart-workflow.yml
    name: Swell Create Cart and Apply Coupon
    summary: Create a backend cart with items and apply a coupon code to it.
  - url: arazzo/swell-io-build-cart-convert-order-workflow.yml
    name: Swell Build Cart and Convert to Order
    summary: Create a cart, populate its items, then convert it into an order.
  - url: arazzo/swell-io-cancel-subscription-workflow.yml
    name: Swell Find and Cancel Active Subscription
    summary: Locate an account's active subscription and cancel it, branching when none exists.
  - url: arazzo/swell-io-capture-refund-payment-workflow.yml
    name: Swell Capture and Refund Payment
    summary: Record a payment against an order, then issue a refund against that payment.
  - url: arazzo/swell-io-categorize-product-workflow.yml
    name: Swell Create Category and Product
    summary: Create a category and then create a product assigned to that category.
  - url: arazzo/swell-io-create-product-workflow.yml
    name: Swell Create and Verify Product
    summary: Create a product in the catalog and immediately retrieve it to confirm it was stored.
  - url: arazzo/swell-io-create-subscription-workflow.yml
    name: Swell Create and Verify Subscription
    summary: Create a recurring subscription for an account and product, then read it back.
  - url: arazzo/swell-io-find-or-create-customer-order-workflow.yml
    name: Swell Find-or-Create Customer and Order
    summary: Look up a customer by email and reuse it or create it, then place an order.
  - url: arazzo/swell-io-onboard-customer-order-workflow.yml
    name: Swell Onboard Customer and Place Order
    summary: Create a customer account and immediately place an order for that account.
  - url: arazzo/swell-io-storefront-apply-coupon-workflow.yml
    name: Swell Storefront Validate and Apply Coupon
    summary: Validate a coupon code, then apply it to the session cart only when it is valid.
  - url: arazzo/swell-io-storefront-checkout-workflow.yml
    name: Swell Storefront Add Item and Submit Order
    summary: Look up a product, add it to the session cart, then submit the cart as an order.
  - url: arazzo/swell-io-storefront-register-login-workflow.yml
    name: Swell Storefront Register and Log In
    summary: Create a storefront customer account and immediately authenticate the session.
  - url: arazzo/swell-io-storefront-update-cart-item-workflow.yml
    name: Swell Storefront Adjust Cart Item Quantity
    summary: Read the session cart, then update the quantity of one of its line items.
- url: https://www.swell.is/
  type: Homepage
- url: https://www.swell.is/
  type: DeveloperPortal
- url: https://developers.swell.is
  type: Documentation
- url: https://developers.swell.is/guides/quickstart-guide
  type: Quickstart
- url: https://developers.swell.is/guides/core-concepts/platform-overview
  type: GettingStarted
- url: https://www.swell.is/features
  type: Features
  name: Features Overview
- url: https://www.swell.is/pricing
  type: Pricing
- url: https://swell.store/signup
  type: SignUp
- url: https://swell.store/admin/login
  type: Login
- url: https://swell.store/admin
  type: Console
- url: https://status.swell.store/
  type: StatusPage
- url: https://www.swell.is/changelog
  type: ChangeLog
- url: https://www.swell.is/blog
  type: Blog
- url: https://www.swell.is/help
  type: Support
- url: https://www.swell.is/contact
  type: Contact
- url: https://www.swell.is/legal/terms-of-service
  type: TermsOfService
- url: https://www.swell.is/legal/privacy-policy
  type: PrivacyPolicy
- url: https://github.com/swellstores
  type: GitHubOrganization
- url: https://github.com/orgs/swellstores/discussions
  type: Forum
  name: Swell Community Discussions
- url: https://x.com/swellcommerce
  type: X
- url: https://www.linkedin.com/company/swellcommerce/
  type: LinkedIn
- url: https://github.com/swellstores/swell-node
  type: SDK
  name: Swell Node.js SDK
- url: https://github.com/swellstores/swell-php
  type: SDK
  name: Swell PHP SDK
- url: https://github.com/swellstores/swell-js
  type: SDK
  name: Swell.js Universal Storefront SDK
- url: https://github.com/swellstores/swellpy
  type: SDK
  name: Swellpy (community Python SDK)
- url: https://github.com/swellstores/apps-sdk
  type: SDK
  name: Swell Apps SDK
- url: https://github.com/swellstores/app-types
  type: SDK
  name: Swell Apps TypeScript Bindings
- url: https://github.com/swellstores/horizon
  type: Resources
  name: Horizon — Headless Next.js Storefront Starter
- url: https://github.com/swellstores/origin-theme
  type: Resources
  name: Origin — Headless Nuxt 2 Storefront Starter
- url: https://github.com/swellstores/verswell-commerce
  type: Resources
  name: verswell-commerce — Next.js Commerce Fork
- url: https://github.com/swellstores/nextjs-commerce
  type: Resources
  name: Swell Next.js Commerce
- url: https://github.com/swellstores/nextjs-builder
  type: Resources
  name: Swell Next.js Builder.io Starter
- url: https://github.com/swellstores/storefront-react-ai-template
  type: Resources
  name: Swell Storefront React AI Template
- url: https://github.com/swellstores/swell-claude-plugins
  type: Resources
  name: Official Claude Code Plugins for Swell
- url: https://github.com/swellstores/skills
  type: Resources
  name: Swell AI Coding-Agent Skills
- url: https://github.com/swellstores/easyblocks
  type: Resources
  name: EasyBlocks — Visual Builder Framework
- url: https://github.com/swellstores/proxima-app
  type: Resources
  name: Proxima — Liquid Storefront App
- url: https://github.com/swellstores/contentful-app
  type: Resources
  name: Swell Contentful CMS App
- url: https://github.com/swellstores/honest-reviews-app
  type: Resources
  name: Honest Reviews Example App
- url: https://github.com/swellstores/community
  type: Resources
  name: Swell Community Discussion Hub
- url: rules/swell-rules.yml
  type: SpectralRules
- url: vocabulary/swell-io-vocabulary.yml
  type: Vocabulary
- url: json-ld/swell-io-context.jsonld
  type: JSONLD
- url: plans/swell-io-plans-pricing.yml
  type: Plans
- url: rate-limits/swell-io-rate-limits.yml
  type: RateLimits
- url: finops/swell-io-finops.yml
  type: FinOps
- name: Features
  type: Features
  data:
  - name: Customizable, API-first core
    description: >-
      Every commerce primitive — products, carts, orders, subscriptions — is exposed as a REST resource with full
      CRUD and rich querying.
  - name: Headless storefront
    description: >-
      Build any storefront — Next.js, Nuxt, Astro, mobile, native — against the public-key Frontend API and Swell.js
      SDK.
  - name: Native subscriptions
    description: >-
      First-class recurring billing with plans, trials, intervals, billing limits, and dunning baked into products
      and orders.
  - name: B2B and wholesale
    description: Account groups, volume pricing, invoicing, and price lists for B2B and wholesale alongside D2C flows.
  - name: Marketplaces
    description: Multi-vendor selling with split fulfillment, vendor accounts, and per-vendor reporting.
  - name: 230 currencies, 170 languages
    description: Built-in internationalization for global stores including priced currencies on higher plans.
  - name: Apps platform with edge functions
    description: >-
      Extend the data model, events, notifications, and admin UI via the Swell Apps platform; functions run in 200+
      locations with no cold start.
  - name: Custom wire protocol
    description: >-
      Official Node and PHP libraries use a custom protocol on port 8443 for improved performance and caching versus
      plain HTTPS.
  - name: MongoDB-style querying
    description: >-
      Powerful `where` filters with comparison, logical, and array operators, plus `expand`, `include`, `sort`,
      `search`, and field projection.
  - name: Webhooks with retries and IP allowlist
    description: >-
      Reliable event delivery with documented retry schedule, auto-disable, and a published source-IP allowlist for
      inbound verification.
  - name: AI coding-agent skills
    description: Official Claude Code plugins and AI coding-agent skills for Swell-aware development workflows.
- name: UseCases
  type: UseCases
  data:
  - name: Direct-to-consumer brands
    description: Power D2C storefronts with full control over product, cart, checkout, and payment UX.
  - name: Subscription commerce
    description: Box-of-the-month, SaaS-style, replenishment, and membership models with native subscription billing.
  - name: B2B and wholesale
    description: Account-group pricing, invoicing, net terms, and bulk ordering for wholesale channels.
  - name: Multi-vendor marketplaces
    description: Operate marketplaces with vendor onboarding, split fulfillment, and per-vendor payouts.
  - name: Headless omnichannel
    description: Serve web, native mobile, in-store, and AI-agent surfaces from a single commerce backend.
  - name: AI-driven commerce
    description: Back conversational commerce agents and AI shopping assistants with a clean, query-rich API.
  - name: Composable enterprise commerce
    description: Combine Swell with best-of-breed CMS, search, payments, ERP, and analytics for enterprise stacks.
- name: Integrations
  type: Integrations
  data:
  - name: Stripe
    description: Default card processing and tokenization for most Swell stores.
  - name: PayPal
    description: PayPal Express, billing agreements, and subscription processing.
  - name: Braintree
    description: Multi-currency card processing.
  - name: Authorize.net
    description: Card processing gateway.
  - name: Amazon Pay
    description: Fast, account-based checkout via Amazon.
  - name: Apple Pay
    description: Mobile wallet payments.
  - name: Google Pay
    description: Digital wallet payments.
  - name: Klarna
    description: Buy-now-pay-later installments.
  - name: Affirm
    description: Buy-now-pay-later financing.
  - name: Paysafecard
    description: Prepaid voucher payments.
  - name: QuickPay
    description: Payment service provider integration.
  - name: 99Minds.io
    description: Omnichannel gift card and loyalty programs.
  - name: Klaviyo
    description: Email, SMS, mobile push, and web marketing automation.
  - name: Mailchimp
    description: Email marketing and automation.
  - name: Omnisend
    description: Email and SMS marketing platform.
  - name: Churn Buster
    description: Subscription retention and dunning.
  - name: Oppizi
    description: Offline marketing campaign attribution.
  - name: Algolia
    description: Hosted product search and discovery.
  - name: Avalara
    description: Sales-tax calculation and filing.
  - name: Contentful
    description: Headless CMS via the official Swell Contentful app.
  - name: Builder.io
    description: Visual page-building CMS.
  - name: Vercel
    description: Frontend deployment and edge hosting for Swell storefronts.
  - name: Anthropic Claude
    description: Official Claude Code plugins and AI coding-agent skills for Swell development workflows.
- name: Solutions
  type: Solutions
  data:
  - name: D2C Commerce
    description: Headless storefronts for direct-to-consumer brands.
  - name: B2B Commerce
    description: Wholesale catalogs, account groups, invoicing, and net-terms billing.
  - name: Subscriptions
    description: Native recurring billing with flexible plans, trials, and limits.
  - name: Marketplaces
    description: Multi-vendor selling with split fulfillment and per-vendor reporting.
  - name: Omnichannel
    description: Serve web, native, in-store, and agent surfaces from a single commerce backend.
  - name: Enterprise
    description: Custom-priced plans for merchants exceeding $10M annual sales with negotiated SLAs.