JavaScript API Methods

The Next Commerce JS SDK exposes methods through the window.next object after initialization.

Caution

Important: Most cart methods require an options object with packageId property, not a direct package ID.

Getting Started

Initialization Detection

// Check if SDK is ready
if (window.next) {
  // SDK is ready, use it directly
  next.addItem({ packageId: 123 });
} else {
  // Queue for later execution
  window.nextReady = window.nextReady || [];
  window.nextReady.push(function() {
    next.addItem({ packageId: 123 });
  });
}

// Or listen for initialization event
document.addEventListener('next:initialized', function(event) {
  console.log('SDK initialized at', new Date(event.detail.timestamp));
  next.addItem({ packageId: 123 });
});

Cart Methods

addItem

Adds an item to the cart. Requires an options object, not a direct package ID.

// ✅ CORRECT - Pass an object with packageId property
await next.addItem({
  packageId: 123,
  quantity: 2
});

// ✅ CORRECT - Quantity is optional (defaults to 1)
await next.addItem({ packageId: 123 });

// ❌ WRONG - Don't pass packageId directly
// next.addItem(123); // This won't work!

Parameters:

• options (object): Required options object
  • options.packageId (number): Package ID to add
  • options.quantity (number, optional): Quantity to add (default: 1)

Returns: Promise<void>

removeItem

Removes an item from the cart. Requires an options object.

// ✅ CORRECT
await next.removeItem({ packageId: 123 });

// ❌ WRONG
// next.removeItem(123); // This won't work!

Parameters:

• options (object): Required options object
  • options.packageId (number): Package ID to remove

Returns: Promise<void>

updateQuantity

Updates the quantity of an item in the cart. Requires an options object.

// ✅ CORRECT
await next.updateQuantity({
  packageId: 123,
  quantity: 5
});

// ❌ WRONG
// next.updateQuantity(123, 5); // This won't work!

Parameters:

• options (object): Required options object
  • options.packageId (number): Package ID to update
  • options.quantity (number): New quantity

Returns: Promise<void>

clearCart

Removes all items from the cart.

await next.clearCart();

Returns: Promise<void>

hasItemInCart

Checks if an item is in the cart. Requires an options object.

// ✅ CORRECT
const hasItem = next.hasItemInCart({ packageId: 123 });
console.log('Item in cart:', hasItem); // true or false

// ❌ WRONG
// next.hasItemInCart(123); // This won't work!

Parameters:

• options (object): Required options object
  • options.packageId (number): Package ID to check

Returns: boolean

getCartData

Returns comprehensive cart data including enriched items, totals, campaign data, and applied coupons.

const cartData = next.getCartData();
console.log(cartData);
// {
//   cartLines: [...],
//   cartTotals: { subtotal: {...}, total: {...}, ... },
//   campaignData: {...},
//   appliedCoupons: [...]
// }

Returns:

{
  cartLines: EnrichedCartLine[];
  cartTotals: CartTotals;
  campaignData: Campaign | null;
  appliedCoupons: AppliedCoupon[];
}

getCartTotals

Returns cart totals and pricing information.

const totals = next.getCartTotals();
console.log('Total:', totals.total.formatted); // "$99.99"
console.log('Subtotal:', totals.subtotal.formatted); // "$89.99"
console.log('Shipping:', totals.shipping.formatted); // "$10.00"

Returns: CartTotals object with subtotal, shipping, tax, discounts, and total

getCartCount

Returns the total number of items in the cart.

const count = next.getCartCount();
console.log('Items in cart:', count); // 3

Returns: number

Campaign & Package Methods

getCampaignData

Returns the loaded campaign data.

const campaign = next.getCampaignData();
if (campaign) {
  console.log('Campaign:', campaign.name);
  console.log('Currency:', campaign.currency);
  console.log('Packages:', campaign.packages);
}

Returns: Campaign | null

getPackage

Gets detailed information about a specific package.

const package = next.getPackage(123);
if (package) {
  console.log('Package name:', package.display_name);
  console.log('Price:', next.formatPrice(package.price));
}

Parameters:

• id (number): Package ID

Returns: Package | null

Profile Methods

Profile methods enable dynamic package ID mapping for different pricing tiers, promotions, and customer segments.

setProfile

Applies a pricing profile to swap package IDs.

// Basic usage
await next.setProfile('black_friday');

// With options
await next.setProfile('vip', {
  clearCart: true,
  preserveQuantities: false
});

revertProfile

Reverts to original packages.

await next.revertProfile();

getActiveProfile

Gets the currently active profile ID.

const profile = next.getActiveProfile();
console.log(profile); // "black_friday" or null

getMappedPackageId

Gets the mapped package ID for the active profile.

const mappedId = next.getMappedPackageId(1);
console.log(mappedId); // 101 (if profile maps 1 -> 101)

listProfiles

Lists all configured profiles.

const profiles = next.listProfiles();
console.log(profiles); // ["regular", "black_friday", "vip"]

Coupon Methods

applyCoupon

Applies a coupon code to the cart.

const result = await next.applyCoupon('SAVE20');
if (result.success) {
  console.log('Coupon applied:', result.message);
  console.log('Discount amount:', result.data.amount);
} else {
  console.error('Coupon error:', result.message);
}

Parameters:

• code (string): Coupon code to apply

Returns:

Promise<{
  success: boolean;
  message: string;
  data?: { amount: number; formatted: string; }
}>

removeCoupon

Removes a coupon from the cart.

next.removeCoupon('SAVE20');

Parameters:

• code (string): Coupon code to remove

Returns: void

getCoupons

Returns all applied coupons.

const coupons = next.getCoupons();
coupons.forEach(coupon => {
  console.log(`${coupon.code}: ${coupon.amount.formatted} off`);
});

Returns: AppliedCoupon[]

validateCoupon

Validates a coupon without applying it.

const validation = next.validateCoupon('TESTCODE');
if (validation.valid) {
  console.log('Coupon is valid');
} else {
  console.log('Invalid:', validation.message);
}

Parameters:

• code (string): Coupon code to validate

Returns:

{
  valid: boolean;
  message?: string;
}

Tracking & Analytics Methods

trackViewItemList

Tracks when users view a list of products.

// Basic tracking
await next.trackViewItemList(['1', '2', '3']);

// With list context
await next.trackViewItemList(
  ['1', '2', '3'],
  'homepage',
  'Featured Products'
);

Parameters:

• packageIds (Array<string|number>): Array of package IDs
• listId (string, optional): Unique list identifier
• listName (string, optional): Human-readable list name

Returns: Promise<void>

trackViewItem

Tracks when a single item is viewed.

await next.trackViewItem('1');

Parameters:

• packageId (string|number): Package ID viewed

Returns: Promise<void>

trackAddToCart

Tracks when an item is added to cart.

await next.trackAddToCart('1', 2);

Parameters:

• packageId (string|number): Package ID added
• quantity (number, optional): Quantity added (default: 1)

Returns: Promise<void>

trackRemoveFromCart

Tracks when an item is removed from cart.

await next.trackRemoveFromCart('1', 1);

Parameters:

• packageId (string|number): Package ID removed
• quantity (number, optional): Quantity removed (default: 1)

Returns: Promise<void>

trackBeginCheckout

Tracks when checkout process begins.

await next.trackBeginCheckout();

Returns: Promise<void>

trackPurchase

Tracks completed purchases.

// Track with order data
await next.trackPurchase(orderData);

Parameters:

• orderData (any): Order data object

Returns: Promise<void>

trackCustomEvent

Tracks custom events with optional data.

// Simple custom event
await next.trackCustomEvent('video_played');

// Custom event with data
await next.trackCustomEvent('user_engagement', {
  section: 'hero',
  action: 'video_play',
  duration: 30
});

Parameters:

• eventName (string): Custom event name
• data (Record<string, any>, optional): Additional event data

Returns: Promise<void>

Shipping Methods

getShippingMethods

Returns all available shipping methods from the campaign.

const methods = next.getShippingMethods();
console.log(methods);
// [
//   {ref_id: 1, code: "standard", price: "0.00"},
//   {ref_id: 2, code: "express", price: "12.99"}
// ]

Returns: Array<{ref_id: number; code: string; price: string}>

getSelectedShippingMethod

Returns the currently selected shipping method.

const selected = next.getSelectedShippingMethod();
if (selected) {
  console.log('Shipping:', selected.name, selected.price);
}

Returns: {id: number; name: string; price: number; code: string} | null

setShippingMethod

Sets the shipping method by ID.

// Set standard shipping (ID 1)
await next.setShippingMethod(1);

// Set express shipping (ID 2)
await next.setShippingMethod(2);

Parameters:

• methodId (number): The ref_id of the shipping method from campaign data

Returns: Promise<void>

Throws: Error if shipping method ID is not found in campaign data

Upsell Methods

addUpsell

Adds upsell items to a completed order. Only available after order completion.

// Add single upsell
const result = await next.addUpsell({
  packageId: 123,
  quantity: 1
});

// Add multiple upsells at once
const result = await next.addUpsell({
  items: [
    { packageId: 123, quantity: 1 },
    { packageId: 456, quantity: 2 }
  ]
});

console.log('Upsells added:', result.addedLines);
console.log('Total upsell value:', result.totalValue);

Parameters:

• options.packageId (number, optional): Single package ID to add
• options.quantity (number, optional): Quantity for single item (default: 1)
• options.items (Array, optional): Multiple items to add
  • items[].packageId (number): Package ID
  • items[].quantity (number, optional): Quantity (default: 1)

Returns:

Promise<{
  order: Order;
  addedLines: OrderLine[];
  totalValue: number;
}>

Throws: Error if no order exists or order doesn’t support upsells

canAddUpsells

Checks if upsells can be added to the current order.

if (next.canAddUpsells()) {
  console.log('Order supports upsells');
}

Returns: boolean

Behavioral Methods

fomo

Starts FOMO (Fear of Missing Out) popup notifications showing recent purchases.

// Start with default configuration
await next.fomo();

// Start with custom configuration
await next.fomo({
  items: [
    { text: "Premium Package", image: "/images/product1.jpg" },
    { text: "Starter Bundle", image: "/images/product2.jpg" }
  ],
  customers: {
    US: ["John", "Sarah", "Mike", "Emma"],
    GB: ["James", "Sophie", "Oliver", "Lily"]
  },
  maxMobileShows: 2,
  displayDuration: 5000,
  delayBetween: 12000,
  initialDelay: 3000
});

Parameters:

• config (object, optional):
  • items (Array): Custom product items to show
  • customers (object): Customer names by country code
  • maxMobileShows (number): Max popups on mobile (default: 2)
  • displayDuration (number): How long to show each popup in ms (default: 5000)
  • delayBetween (number): Delay between popups in ms (default: 12000)
  • initialDelay (number): Initial delay before first popup in ms (default: 3000)

Returns: Promise<void>

stopFomo

Stops FOMO popup notifications.

next.stopFomo();

Returns: void

exitIntent

Shows exit intent popup when user tries to leave the page.

await next.exitIntent({
  image: 'https://example.com/special-offer.jpg',
  action: async () => {
    // Apply discount when popup is clicked
    await next.applyCoupon('EXIT20');
    // Close the popup
  }
});

Parameters:

• options.image (string): URL of the image to display
• options.action (function, optional): Function to call when popup is clicked

Returns: Promise<void>

disableExitIntent

Disables the exit intent popup.

next.disableExitIntent();

Returns: void

Event Methods

on

Subscribe to internal SDK events.

// Listen for cart updates
next.on('cart:updated', (cartState) => {
  console.log('Cart updated:', cartState.items.length, 'items');
});

// Listen for item additions
next.on('cart:item-added', (data) => {
  console.log('Item added:', data.packageId);
});

Parameters:

• event (string): Event name from EventMap
• handler (function): Event handler function

Returns: void

off

Unsubscribe from internal SDK events.

const handler = (data) => console.log(data);
next.on('cart:updated', handler);
// Later...
next.off('cart:updated', handler);

Parameters:

• event (string): Event name
• handler (function): Handler function to remove

Returns: void

Available Events

// Cart events
next.on('cart:updated', (cartState) => { /* ... */ });
next.on('cart:item-added', (data) => { /* ... */ });
next.on('cart:item-removed', (data) => { /* ... */ });
next.on('cart:quantity-changed', (data) => { /* ... */ });

// Campaign events
next.on('campaign:loaded', (campaign) => { /* ... */ });

// Checkout events
next.on('checkout:started', (data) => { /* ... */ });
next.on('checkout:form-initialized', () => { /* ... */ });

// Order events
next.on('order:completed', (order) => { /* ... */ });

// Payment events
next.on('payment:tokenized', (data) => { /* ... */ });
next.on('payment:error', (error) => { /* ... */ });

// Coupon events
next.on('coupon:applied', (coupon) => { /* ... */ });
next.on('coupon:removed', (code) => { /* ... */ });

// Upsell events
next.on('upsell:added', (data) => { /* ... */ });
next.on('upsell:skipped', (data) => { /* ... */ });
next.on('upsell:viewed', (data) => { /* ... */ });
next.on('upsell:accepted', (data) => { /* ... */ });

// Other events
next.on('error:occurred', (error) => { /* ... */ });
next.on('config:updated', (config) => { /* ... */ });
next.on('fomo:shown', (data) => { /* ... */ });
next.on('route:changed', (route) => { /* ... */ });

Utility Methods

formatPrice

Formats a price value according to campaign currency.

const formatted = next.formatPrice(19.99); // "$19.99"
const euros = next.formatPrice(19.99, 'EUR'); // "€19.99"

Parameters:

• amount (number): Price amount to format
• currency (string, optional): Currency code (uses campaign currency if not provided)

Returns: string

validateCheckout

Validates if the cart is ready for checkout.

const validation = next.validateCheckout();
if (!validation.valid) {
  console.error('Cannot checkout:', validation.errors);
}

Returns:

{
  valid: boolean;
  errors?: string[];
}

registerCallback

Register a callback for specific SDK operations (legacy compatibility).

next.registerCallback('itemAdded', (data) => {
  console.log('Item added:', data);
  // data includes: cartLines, cartTotals, campaignData, appliedCoupons
});

Parameters:

• type (CallbackType): Type of callback. Available types:
  • 'beforeRender' - Before cart UI renders
  • 'afterRender' - After cart UI renders
  • 'beforeCheckout' - Before checkout starts
  • 'afterCheckout' - After checkout completes
  • 'beforeRedirect' - Before order redirect
  • 'itemAdded' - After item added to cart
  • 'itemRemoved' - After item removed from cart
  • 'cartCleared' - After cart cleared
• callback (function): Callback function that receives CallbackData

Returns: void

Debug API

The debug API provides powerful utilities for development and troubleshooting. Available only when debug mode is enabled with ?debugger=true.

Accessing Debug Mode

// Check if debug mode is available
if (window.nextDebug) {
  console.log('Debug mode available');
}

Store Access

Direct access to all internal stores:

// Cart store
const cartState = nextDebug.stores.cart.getState();
console.log('Cart items:', cartState.items);

// Campaign store
const campaignState = nextDebug.stores.campaign.getState();
console.log('Campaign data:', campaignState.data);

// Config store
const configState = nextDebug.stores.config.getState();
console.log('API key:', configState.apiKey);

// Checkout store
const checkoutState = nextDebug.stores.checkout.getState();

// Order store
const orderState = nextDebug.stores.order.getState();

// Attribution store
const attributionState = nextDebug.stores.attribution.getState();

Cart Debug Methods

// Quick cart operations
nextDebug.addToCart(123);        // Add single item
nextDebug.addToCart(123, 3);     // Add with quantity
nextDebug.removeFromCart(123);   // Remove item
nextDebug.updateQuantity(123, 5); // Update quantity

// Add test items (packages 2, 7, 9)
nextDebug.addTestItems();

Error Handling

Standard Error Handling

try {
  await next.addItem({ packageId: 123, quantity: 2 });
  console.log('Item added successfully');
} catch (error) {
  console.error('Failed to add item:', error.message);
}

Async Method Handling

// Most cart/coupon methods are async
const result = await next.applyCoupon('INVALID_CODE');
if (!result.success) {
  console.error('Coupon error:', result.message);
  // Show user-friendly message
}

Event Error Handling

next.on('error:occurred', (error) => {
  console.error('SDK error:', error);
  // Handle errors gracefully
});

Best Practices

1. Always wait for SDK initialization before calling methods
2. Use async/await for cleaner code with promises
3. Handle errors appropriately - check success flags and catch exceptions
4. Subscribe to events for reactive UI updates
5. Use debug mode during development for troubleshooting
6. Batch operations when possible for better performance
7. Validate inputs before calling methods
8. Clean up event listeners when no longer needed

Common Patterns

E-commerce Flow

window.nextReady.push(async function() {
  // 1. Track product list view
  await next.trackViewItemList(['1', '2', '3'], 'category', 'Best Sellers');

  // 2. Add item to cart
  await next.addItem({ packageId: 1, quantity: 2 });

  // 3. Apply coupon
  const couponResult = await next.applyCoupon('SAVE20');
  if (couponResult.success) {
    console.log('Discount applied');
  }

  // 4. Track checkout start
  await next.trackBeginCheckout();
});

Reactive Cart Updates

// Update UI when cart changes
next.on('cart:updated', (cartState) => {
  document.querySelector('.cart-count').textContent = next.getCartCount();
  document.querySelector('.cart-total').textContent = cartState.totals.total.formatted;
});

// React to specific actions
next.on('cart:item-added', (data) => {
  showNotification(`${data.packageName} added to cart`);
});

Related Documentation

• Events - Event system reference
• Callbacks - Legacy callback patterns
• Cart Methods - Detailed cart operations
• Analytics - Tracking and analytics