Campaigns API

Campaigns App opens up new possibilities for frontend developers to easily create complex external campaign flows using Javascript, no backend server-side integration required.

The Campaigns App provides an easy to use CORS enabled API that follows the best practices for integrating to our Admin API for an External Checkout Flow.

Recommended: use the Campaign Cart SDK

For most projects, start with the Campaigns Getting Started guide — it walks you through scaffolding a working funnel with Page Kit and the Campaign Cart SDK, which wraps every endpoint on this page behind data-attribute driven add-to-cart, live cart state, coupon handling, checkout forms, and upsell flows. You write HTML, not fetch calls. The Cart System and JavaScript API docs cover the SDK in depth.

Use the raw API on this page only for custom server-side flows or backend integrations the SDK doesn't cover.

Campaigns Overview

A "campaign" is a defined set of packages and payment rules as a backend for the HTML/JS webpages of a campaign (or funnel) frontend. You can easily setup multiple campaigns for different product offers, markets, and A/B testing.

Session Tracking

Session tracking is available to enable visibility into campaign performance by adding a javascript snippet to the head of every page on your campaign. With session tracking configured, we'll automatically track events for:

Page Veiw
Cart Create
Order Create
Upsell Create

These events flow into Campaign Performance reports for real time monitoring of acvitities on your campaign.

Packages

A package is a virtual link to a product in your campaign — what customers reference by package_id when creating carts and orders. Each package points to one product with a default quantity (e.g. 1x or 3x for bundles), and can optionally be recurring (subscription).

Pricing adjustments — per-quantity bundle discounts, automatic offers, coupon codes — are controlled by offers, not by per-package pricing rules. The cart and order APIs return adjusted before/after totals so the frontend can render savings without doing math.

See Concepts → Packages and Concepts → Offers for the full model.

Shipping Options

Campaigns can have custom shipping prices to optimize shipping fees and methods available on your campaign to override the default pricing configured globally in the store.

Example Shipping Methods

Shipping Method 1 - Default shipping at 7.99
Shipping Method 2 - Express shipping at 14.99

Offers

Offers are the pricing layer. They apply discounts to the cart when conditions are met — either automatically (when the cart line/quantity matches an offer's rule) or via a coupon code the customer enters.

Coupon codes are submitted through the vouchers array on cart, order, and upsell-create requests. Codes stack on top of automatic offers, and they're the only way to apply discounts on upsell pages (automatic offers don't run there).

The cart and order responses include applied discounts, total_discounts, and per-line discount breakdowns so the frontend can render savings without recalculating. The full set of offers configured on a campaign is returned by campaignRetrieve.

See Concepts → Offers for the full model.

Getting Started

To get started, create a new campaign with a package mapped to a product in your store. Use the examples below with your Campaign API Key to get started using the Campaigns API.

Add Session Tracking

Add the script below to every page of your campaign for full session tracking integration.

<script async src="https://campaigns.apps.29next.com/js/v1/campaign/"></script>
<script>
    window.addEventListener('load', function () {
        nextCampaign.config({
            apiKey: "<YOUR CAMPAIGN API KEY>",
        })
        nextCampaign.event('page_view', {
            title: document.title,
            url: window.location.href
        });
    });
</script>

Calculate Cart

Show customers a live pricing preview — subtotal, discounts, shipping, total — before they commit to creating an order. Use this on checkout pages to update totals as the user changes quantity, swaps packages, or enters a coupon code. No cart is persisted; the endpoint accepts the same lines/vouchers shape as cart create and returns adjusted totals plus a breakdown of applied offer and voucher discounts.

Calculate Cart Totals

var payload = {
  "lines": [
    { "package_id": 1 }
  ],
  "vouchers": ["SAVE10"], // optional coupon codes
  "shipping_method": 1    // optional — include to factor shipping into the total
}
const response = await fetch('https://campaigns.apps.29next.com/api/v1/carts/calculate/', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        "Authorization": '<YOUR CAMPAIGN API KEY>' // Campaign API Key
    },
    body: JSON.stringify(payload),
});
const result = await response.json();
console.log(result); // subtotal, total, total_discount, offer_discounts, voucher_discounts, lines

Calculating on upsell pages

Add ?upsell=true to the URL when calling from an upsell page — this skips site-wide automatic offers (which don't apply post-purchase). Coupon codes passed via vouchers still apply.

Create Cart

Capture customer details (email, name) alongside their selected packages and persist the cart server-side — so the visitor is recorded as a lead even if they don't complete checkout. Use this on email-gate or "reserve your order" steps to feed abandoned-cart recovery and lead capture flows. Carts can be referenced later or converted into an order via Create Order.

Create a Cart

var payload = {
  "user": {
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe"
  },
  "lines": [
    {
        "package_id": 1
    }
  ],
  "attribution": {
    "utm_source": "Example Campaign"
  }
}
const response = await fetch('https://campaigns.apps.29next.com/api/v1/carts/', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        "Authorization": '<YOUR CAMPAIGN API KEY>' // Campaign API Key
    },
    body: JSON.stringify(payload),
});
const result = await response.json()
console.log(result); // Show result in console

Create Order

Creating an order is the core method in an external checkout flow, see the example below to familiarize yourself with the payload data required.

The `success_url` Explained

All orders require a success_url to handle payments requiring a redirect flow. The success_url should be the absolute URL of the "Next Page" in your campaign flow. In most cases, this should be your first upsell page, see more below in Adding Upsells on retrieving order details and handling payment methods that support upsells.

Create an Order

var payload = {
    "user": {
        "email": "[email protected]",
        "first_name": "John",
        "last_name": "Doe"
    },
    "lines": [
        {
            "package_id": 1
        },
        {
            "package_id": 2,
            "is_upsell": true
        }
    ],
    "shipping_address": {
        "first_name": "string",
        "last_name": "string",
        "line1": "string",
        "line4": "string",
        "state": "string",
        "postcode": "string",
        "phone_number": "string",
        "country": "string"
    },
    "billing_same_as_shipping_address": false,
    "payment_detail": {
        "payment_method": "card_token",
        "card_token": "test_card" // See iFrame Payment Form Guide
    },
    "shipping_method": 1,
    "success_url": "https://your-campaign.com/next-page/" // Next Page in Flow
    "payment_failed_url": "https://your-campaign.com/decline-flow/" // Optional Decline Page
    "attribution": {
        "utm_source": "Example Campaign"
    }
}
const response = await fetch('https://campaigns.apps.29next.com/api/v1/orders/', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        "Authorization": '<YOUR CAMPAIGN API KEY>' // Campaign API Key
    },
    body: JSON.stringify(payload),
});
const result = await response.json();
console.log(result); // Show result in console

iFrame Payment Form

Bankcard payments require using the iFrame Payment Form and passing the generated card_token for secure transfer of the payment method details. View a fully functional Demo.

You Must Handle the Order Create Response

If response data has a number, order was successfully created, you can redirect to the next page.
If response data has a payment_complete_url, redirect the user to this page. After payment, user will come back to your success_url or payment_failed_url.

Handle APM Redirect Flow Declines

If an APM redirect flow declines or is canceled, by default the user is redirected back to the HTTP referrer with contexual querystings, ie ?payment_failed=true&payment_method=paypal.

Pass payment_failed_url to more explicitly control the decline handling for APM redirect flows.

Adding Upsells

To add an upsell to an existing order, first you should check to see if the order payment method supports_post_purchase_upsells is True in the orderRetrieve response.

Retrieve Order Details

const refId = '<YOUR ORDER REF ID>'
const response = await fetch('https://campaigns.apps.29next.com/api/v1/orders/' + refId + '/', {
    method: 'GET',
    headers: {
        'Content-Type': 'application/json',
        "Authorization": '<YOUR CAMPAIGN API KEY>' // Campaign API Key
    }
});
const result = await response.json();
console.log(result); // Show result in console

If the order supports_post_purchase_upsells, you can add an upsell to an order can be done using the orderUpsellCreate API endpoint.

Add Upsell to Order

const refId = '<YOUR ORDER REF ID>'
var payload = {
    "lines": [
        {
            "package_id": 1
        }
    ]
}
const response = await fetch('https://campaigns.apps.29next.com/api/v1/orders/' + refId + '/upsells/', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        "Authorization": '<YOUR CAMPAIGN API KEY>' // Campaign API Key
    },
    body: JSON.stringify(payload),
});
const result = await response.json();
console.log(result);

Order Confirmation

On the order confirmation page, you can retrieve the order details and map the values to your template to show an order summary to the customer.

Retrieve Order Details

const refId = '<YOUR ORDER REF ID>'
const response = await fetch('https://campaigns.apps.29next.com/api/v1/orders/' + refId + '/', {
    method: 'GET',
    headers: {
        'Content-Type': 'application/json',
        "Authorization": '<YOUR CAMPAIGN API KEY>' // Campaign API Key
    }
});
const result = await response.json();
console.log(result); // Show result in console

On this page