Introduction

Campaigns enable developers to build fully custom external checkout experiences using HTML and JavaScript — no backend server-side integration required. Each campaign is backed by a headless, CORS-enabled API that handles products, pricing, payments, and order creation.

You can create multiple campaigns for different product offers, markets, and A/B testing, each with its own set of packages, offers, and shipping options.

Core Concepts

Campaigns

A campaign is the top-level configuration that ties together everything needed for an external checkout flow:

• Packages — what products are being sold, at what quantities and prices
• Offers — discounts that apply automatically or via voucher codes
• Shipping Options — available shipping methods and prices
• Payment Methods — which payment methods customers can use
• Currency & Language — localization settings for the checkout

Each campaign has a unique API Key used to authenticate all API requests. Campaigns are created and managed in the Next Commerce dashboard via the Campaigns App.

Domains

Domains are configured in your store's global Campaign Settings and apply across all campaigns for that store. They control which domains are authorized to use your campaign API keys.

There are two domain types:

Production domains are your live, customer-facing domains. When the SDK runs on a production domain, all configured analytics providers automatically track events (page views, add to cart, purchases, etc.).

Development domains are for local development and staging environments (e.g., localhost, staging.example.com). The SDK is fully functional on development domains — cart, checkout, and payment flows all work — but analytics events are suppressed to keep your production data clean.

Available Payment Methods

Campaign responses include available_payment_methods and available_express_payment_methods, which you can use to render only the payment buttons supported by the campaign's gateway group, market, and configured payment methods.

Packages

A package is a virtual link to a product variant (SKU) in your store catalog with a custom quantity and custom pricing. Packages are what customers actually purchase in a campaign — they let you create different purchasing options for the same product without changing the product itself.

For example, a single product could have multiple packages offering different quantities at different price points:

• 1x Widget — 1 unit at $10.00
• 3x Widget Bundle — 3 units at $7.00 each ($21.00 total)
• 5x Widget Best Value — 5 units at $6.00 each ($30.00 total)

Packages can also be configured as recurring for subscription products, with a custom interval (e.g. every 30 days).

Offers

Offers control pricing discounts based on how many packages a customer adds to their order. Packages in an order can be any mix of variants — for example, 1 white and 1 black of the same product both count toward the offer condition.

There are two types of offers:

• Offer — automatically applies when the order meets the condition
• Code — only applies when the code is applied to the order

Offers can also be stacked — for example, an automatic quantity discount and a voucher code can both apply to the same order. When offers apply, the API returns adjusted before/after pricing so you can display savings to the customer.

Typical Campaign Flow

A campaign funnel guides customers through a series of pages, each backed by the Campaigns API:

• Landing — Marketing page that drives traffic to the campaign
• Checkout — Customer selects package, enters shipping, billing, and payment details
• Upsells — Post-purchase offers to increase order value
• Receipt — Order confirmation with details

Integration Options

There are two ways to build your campaign frontend:

Quick Start

Option 1: Use Starter Template (Recommended)

Get started quickly with our pre-configured starter template:

Download Starter Template — Clone or download a ready-to-use campaign flow (landing → checkout → upsell → receipt) with Campaign Cart integrated.

Option 2: Manual Setup

1. Get Your API Key

   Go to Next Commerce Dashboard, open the Campaigns app, select your campaign, click on Integration, and copy your API key.

2. Add SDK Script

   Add these two lines to your HTML <head> section:

   <!-- Path to Your Campaign Cart Configuration -->
   <script src="js/config.js"></script>
   
   <!-- Campaign Cart SDK -->
   <!-- Replace @v0.3.10 with the latest version from GitHub releases -->
   <script src="https://cdn.jsdelivr.net/gh/NextCommerceCo/[email protected]/dist/loader.js" type="module"></script>

   Latest Version

   Check the GitHub releases for the latest stable version. For development, you can use @latest, but we recommend pinning to a specific version (e.g., @v0.3.10) in production for stability.

3. Start Building

   You can now use Campaign Cart attributes in your HTML!

HTML Page Setup

<!DOCTYPE html>
<html>
<head>
  <!-- 1. Set configuration -->
  <script>
    window.dataLayer = window.dataLayer || [];
    window.nextReady = window.nextReady || [];

    window.nextConfig = {
      apiKey: "your-api-key-here",
    };
  </script>

  <!-- 2. Meta tag configuration -->
  <!-- Page Type: product, checkout, upsell, or receipt -->
  <meta name="next-page-type" content="product">

  <!-- Next URL: Redirect after order completion (for checkout pages) -->
  <meta name="next-success-url" content="/upsell">

  <!-- 3. Load the SDK -->
  <!-- Replace @v0.3.10 with the latest version from GitHub releases -->
  <script src="https://cdn.jsdelivr.net/gh/NextCommerceCo/[email protected]/dist/loader.js" type="module"></script>
</head>
<body>
  <!-- Your content here -->
</body>
</html>

Quick Examples

Add to Cart Button

<button data-next-action="add-to-cart"
        data-next-package-id="1"
        data-next-quantity="1">
  Add to Cart
</button>

Product Selector

<div data-next-cart-selector data-next-selection-mode="swap">
  <div data-next-selector-card data-next-package-id="1">Option 1</div>
  <div data-next-selector-card data-next-package-id="2">Option 2</div>
</div>

Display Cart Total

<span data-next-display="cart.total">$0.00</span>

Conditional Display

<div data-next-show="cart.hasItems">
  <button onclick="checkout()">Proceed to Checkout</button>
</div>

Verify the SDK Loaded

Open your browser console and run:

console.log(window.next ? 'SDK Loaded' : 'SDK Not Found');

if (window.next) {
  console.log('SDK Version:', next.version);
  console.log('Config:', next.getConfig());
}

The SDK supports all modern browsers: Chrome, Firefox, Safari, and Edge.