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
  - url: capabilities/catalog-management.yaml
    type: NaftikoCapability
  - url: capabilities/order-fulfillment.yaml
    type: NaftikoCapability
  - url: capabilities/subscription-lifecycle.yaml
    type: NaftikoCapability
  - url: capabilities/customer-management.yaml
    type: NaftikoCapability
  - url: capabilities/discount-promotions.yaml
    type: NaftikoCapability
  - url: capabilities/webhooks.yaml
    type: NaftikoCapability
  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
  - url: capabilities/cart-checkout.yaml
    type: NaftikoCapability
  - url: capabilities/storefront-content.yaml
    type: NaftikoCapability
  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
  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: [email protected]
  url: https://kinlane.com
common:
- 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.