Next Commerce Developer Documentation — Agent Context

This file is a contextual reference for AI agents and onboarding developers. It maps the platform architecture, documentation structure, conventions, and known gaps to enable effective navigation, contribution, and refactoring of the developer docs.

Platform Overview

Next Commerce is a multi-channel ecommerce platform. Merchants manage a single store while selling through multiple independent sales channels. All channels funnel orders, customers, and transaction data into the central store.

Three sales channels and three APIs form the core developer surface:

┌─────────────────────────────────────────────────────────┐
│                    Next Commerce Store                   │
│         (Orders, Products, Customers, Subscriptions)    │
├──────────────┬──────────────────┬───────────────────────┤
│  Storefront  │    Campaigns     │      Admin API        │
│   Themes     │  (External DTC   │  (Server-to-Server)   │
│ (Catalog +   │   Funnels)       │                       │
│  Checkout)   │                  │                       │
├──────────────┼──────────────────┼───────────────────────┤
│ Storefront   │  Campaigns API   │     Admin API         │
│ API (GraphQL)│  (REST, CORS)    │  (REST, OAuth 2.0)    │
└──────────────┴──────────────────┴───────────────────────┘
         ▲               ▲                ▲
         │               │                │
    Webhooks ─────── Event Backbone ──────┘
    (23 event types, HMAC signed, versioned)

Sales Channels

1. Storefront Themes

Full-featured online store with product catalog, collections, customer accounts, and built-in checkout.

Template language — Jinja-like with custom tags, filters, and objects (products, cart, customer, etc.)
Theme Kit CLI — local development, watch mode, Git-based deployment
Theme structure — assets/, checkout/, configs/, layouts/, locales/, partials/, sass/, templates/
Settings — settings_schema.json defines merchant-configurable options rendered in the dashboard
Storefront API — GraphQL API accessible within the storefront context for cart mutations and data queries
CDN & caching — built-in asset CDN with cache management

Primary audience: Theme developers building branded shopping experiences.

2. Campaigns

Isolated external sales funnels for DTC (direct-to-consumer) marketers. Each campaign has its own packages, offers, shipping options, and API key. No backend required — campaigns run entirely client-side.

Core concepts:

Campaign — top-level config tying together packages, offers, shipping, payment methods, currency
Packages — virtual product+quantity+price bundles (not actual products; mapped to store variants)
Offers — automatic or code-based discounts based on package quantity
Flow — Landing → Checkout → Upsell(s) → Receipt

Two integration approaches:

Approach	Method	Best For
Campaign Cart SDK	Declarative HTML `data-next-*` attributes + optional JS API	Fast development, no custom JS needed
Campaigns API	Headless REST API (CORS-enabled, API key auth)	Full programmatic control

Campaign Cart SDK features:

window.nextConfig or meta tag configuration
Data attributes for actions, display, checkout, profiles, state
JavaScript API with methods and events (add_to_cart, begin_checkout, purchase)
Analytics integrations (GTM, Meta Pixel, GA4, RudderStack, custom webhooks)
Utilities: FOMO notifications, exit intent, loading states, debugger
Post-purchase upsell flows

Primary audience: DTC marketers and frontend developers building high-converting campaign funnels.

3. Admin API (as Sales Channel)

The Admin API supports a complete order creation flow with payment processing, enabling fully custom checkout experiences built server-side. This makes it a sales channel in its own right — not just a management API.

Key capabilities as a channel:

Create orders with payment (credit card, PayPal, Klarna, Apple Pay, Google Pay, etc.)
External checkout flow with server-side control
3DS2 authentication support
Subscription/recurring billing creation
iFrame payment form for PCI-compliant card collection

Primary audience: Backend developers building custom commerce applications, integrations, and services.

APIs

Storefront API

Type: GraphQL
Auth: Accessible only within storefront context (on the store domain)
Capabilities: Cart management (createCart, addCartLines, removeCartLines), product/collection queries
Discovery: GraphiQL explorer available in-browser on the storefront
Docs: docs/storefront/api.md (single file)
Note: External access planned but not yet available

Campaigns API

Type: REST, CORS-enabled (browser-safe)
Auth: Campaign API key
Capabilities: Cart creation, order creation, upsell creation, order retrieval, session tracking, shipping options
OpenAPI spec: static/api/campaigns/v1.yaml
Docs: docs/campaigns/api.md

Admin API

Type: REST
Auth: OAuth 2.0 with permission scoping
Rate limit: 4 requests/second
Versions:
- 2023-02-10 — stable
- 2024-04-01 — stable, recommended
- unstable — development
Capabilities: Full CRUD on all store resources (orders, products, customers, subscriptions, fulfillments, gateways, webhooks, etc.)
OpenAPI specs: static/api/admin/2023-02-10.yaml, static/api/admin/2024-04-01.yaml, static/api/admin/unstable.yaml
Docs: docs/admin-api/ (overview, permissions, 15 feature guides)

Admin API guides focus areas:

Payment methods: Apple Pay, Google Pay, PayPal, Klarna, Bancontact, iDEAL, SEPA Debit, TWINT, 3DS2
Core features: External Checkout, Order Management, Subscription Management, Testing
Payment collection: iFrame Payment Form

Webhooks

Event-driven notifications for external systems to stay synced with store activity.

23 event types spanning: app, cart, customer, dispute, fulfillment, gateway, order, product, subscription, store, ticket, transaction
Payload structure: { object, data, event_id, event_type, webhook, api_version }
Verification: HMAC SHA256 via X-29Next-Signature header
Retry policy: Up to 10 retries with exponential backoff; failing webhooks trigger admin email notifications and eventual deactivation
Versioning: Payload data structures align with Admin API versions
Setup: Dashboard (Settings > Webhooks) or Admin API
Docs: docs/webhooks.md (single comprehensive file)

Apps

Apps extend platform functionality by combining Admin API, Webhooks, and Storefront hooks into installable packages.

Two app types:

Server-to-Server — backend integrations (fulfillment services, dispute management, external reporting)
Storefront Extensions — inject snippets, scripts, and event tracking into themes

App infrastructure:

OAuth 2.0 authorization code flow for installation
Manifest-driven configuration
Remote settings management
Asset hosting for static files
Snippet injection into storefronts
Event tracking integration
App review process for publishing

Docs: docs/apps/ (18 files covering development flow, OAuth, manifests, settings, guides)

Documentation Structure

docs/
├── index.md                    → Getting Started landing page
├── admin-api/
│   ├── index.md                → Admin API overview + auth
│   ├── permissions.md          → OAuth permission scopes
│   └── guides/                 → 15 feature guides (payments, orders, subscriptions)
├── apps/
│   ├── index.md                → Apps overview
│   ├── app-kit.md              → App development framework
│   ├── app-development-flow.md → End-to-end dev process
│   ├── manifest.md             → App manifest spec
│   ├── settings.md             → Remote settings
│   ├── assets.md               → Asset hosting
│   ├── snippets.md             → Storefront code injection
│   ├── event-tracking.md       → Storefront event hooks
│   ├── review.md               → App review process
│   ├── oauth/                  → OAuth flows (4 files)
│   └── guides/                 → App pattern guides (4 files)
├── campaigns/
│   ├── index.md                → Campaign concepts + getting started
│   ├── api.md                  → Campaigns API overview + endpoints
│   └── campaign-cart/          → Campaign Cart SDK (largest section, ~48 files)
│       ├── index.md            → Quick start + configuration
│       ├── data-attributes/    → HTML attribute reference (8 files)
│       ├── javascript-api/     → JS API reference (5 files)
│       ├── analytics/          → Analytics integrations (9+ files)
│       ├── guides/             → Implementation guides
│       ├── utilities/          → FOMO, exit intent, loading, debugger
│       └── upsells/            → Post-purchase upsell flows
├── storefront/
│   ├── index.md                → Storefront overview
│   ├── api.md                  → Storefront GraphQL API
│   ├── event-tracking.md       → Event tracking
│   └── themes/
│       ├── index.md            → Theme structure + basics
│       ├── settings.md         → Theme settings schema
│       ├── theme-kit.md        → Theme Kit CLI
│       ├── cdn-and-caching.md  → CDN strategies
│       ├── translations.md     → Multi-language
│       ├── templates/          → Template language reference (5 files)
│       └── guides/             → Theme how-to guides (4 files)
└── webhooks.md                 → Webhook events + verification

static/api/
├── admin/
│   ├── 2023-02-10.yaml         → Admin API v1 OpenAPI spec
│   ├── 2024-04-01.yaml         → Admin API v2 OpenAPI spec
│   └── unstable.yaml           → Admin API unstable spec
└── campaigns/
    └── v1.yaml                 → Campaigns API OpenAPI spec

Documentation Conventions

Navbar (Left)

Label	Path
Getting Started	`/docs/`
Campaigns	`/docs/campaigns/`
Storefront	`/docs/storefront/`
Apps	`/docs/apps/`
Admin API	`/docs/admin-api/`
Webhooks	`/docs/webhooks/`

Tooling

Docusaurus with MDX support
Stoplight Elements for rendering OpenAPI specs inline
Algolia for search
Tailwind CSS for custom components
Sidebar: auto-generated from directory structure (sidebars.js)

Content Patterns

Frontmatter: title, sidebar_label, sidebar_position
Admonitions: :::tip, :::caution, :::info for callouts
Diagrams: Mermaid (graph, sequenceDiagram) for flows and architecture
Code examples: JavaScript, Python, cURL — fenced with language + optional title="..."
Tables: Markdown tables for comparisons, event lists, attribute references
Cross-links: Relative markdown links ([text](/docs/path/to/file.md))
API references: Link to Stoplight-rendered specs (/docs/admin-api/reference/#/...)
MDX components: DocCardList, IntroCards for auto-generated navigation cards

URL Structure

All published docs follow: https://developers.29next.com/docs/{section}/{path}

Key redirects configured in docusaurus.config.js:

/api/ → /docs/api
/docs/admin-api → /docs/admin-api/
/themes → /docs/storefront/themes
/webhooks → /docs/webhooks

Documentation Gaps & Refactoring Opportunities

High Priority

Storefront API is underdocumented
- Currently a single brief file (docs/storefront/api.md) pointing to GraphiQL
- Needs: query/mutation reference, authentication details, available types and fields, usage examples
- Consider: auto-generated reference from GraphQL schema, tutorial-style guides for common operations
Admin API guides skew toward payment methods
- 15 guides, most are payment-specific (Apple Pay, Google Pay, PayPal, Klarna, etc.)
- Missing guides for common workflows: product CRUD, customer management, bulk operations, inventory management
- Opportunity: add "Getting Started with Admin API" tutorial covering basic resource operations
No error handling guide
- No comprehensive documentation on error response formats, common error codes, or handling strategies across APIs
- Each API should document its error format and common failure scenarios

Medium Priority

Rate limiting & quotas
- Admin API mentions 4 req/s but no strategies for handling limits, queuing, or backoff
- No rate limit documentation for Campaigns API or Storefront API
No troubleshooting or FAQ sections
- Common issues (webhook delivery failures, OAuth token expiry, theme deployment problems) lack dedicated troubleshooting docs
Security best practices
- Beyond "don't expose tokens" and webhook HMAC verification, no comprehensive security guide
- Topics: API key rotation, OAuth token storage, CSP headers for campaign pages, PCI considerations
Testing guide is isolated
- Single testing guide in Admin API section; no testing guidance for campaigns, themes, or apps
- Opportunity: cross-cutting testing guide or per-section testing docs

Lower Priority

Getting Started page is thin
- docs/index.md relies on an IntroCards component — could benefit from a brief narrative overview of the platform before the cards
Campaign Cart SDK docs could use restructuring
- At 48 files it's the largest section but has some organizational inconsistencies
- Analytics subsection is thorough but could link back to concepts more clearly
Cross-linking between related sections
- Campaigns intro (docs/campaigns/) could link more explicitly to both SDK and API docs
- Webhook docs could link to app guides that consume webhooks (fulfillment service, dispute service)
- Admin API guides could cross-reference relevant webhook events

Key Repositories

Repository	Purpose
`developer-docs`	This documentation site (Docusaurus)
`campaign-cart-example`	Campaign Cart starter template
`intro` / `intro-bootstrap`	Starter storefront themes
Open-source example apps	Referenced in app documentation

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Next Commerce Developer Documentation — Agent Context

Platform Overview

Sales Channels

1. Storefront Themes

2. Campaigns

3. Admin API (as Sales Channel)

APIs

Storefront API

Campaigns API

Admin API

Webhooks

Apps

Documentation Structure

Documentation Conventions

Navbar (Left)

Tooling

Content Patterns

URL Structure

Documentation Gaps & Refactoring Opportunities

High Priority

Medium Priority

Lower Priority

Key Repositories

FilesExpand file tree

agents.md

Latest commit

History

agents.md

File metadata and controls

Next Commerce Developer Documentation — Agent Context

Platform Overview

Sales Channels

1. Storefront Themes

2. Campaigns

3. Admin API (as Sales Channel)

APIs

Storefront API

Campaigns API

Admin API

Webhooks

Apps

Documentation Structure

Documentation Conventions

Navbar (Left)

Tooling

Content Patterns

URL Structure

Documentation Gaps & Refactoring Opportunities

High Priority

Medium Priority

Lower Priority

Key Repositories