Funnel Navigation

tagada.funnel.navigate() takes the cart from the loaded checkout session, bootstraps an anonymous CMS session, and returns a redirect URL into a specific funnel step. It’s the JS equivalent of the WooCommerce / Shopify checkout plugins — one call from your own site, one URL to redirect to.

When to use it:

The cart lives in your store (Shopify, WooCommerce, PrestaShop, custom) and you want to route the shopper into a TagadaPay marketing funnel.
You want the shopper to enter at a specific funnel step (step_xxx) rather than the funnel default.

When NOT to use it:

You’re building a fully self-hosted checkout page — use Checkout Flow directly. Do not follow createSession().checkoutUrl.
You only need a one-shot Tagada-hosted checkout link without a funnel — use tagada.checkout.createSession() and follow its checkoutUrl.
You need a self-hosted checkout URL with no funnel — use tagada.checkout.createSessionUrl() so the shopper stays on your origin.

Prerequisites

accountId is required on createHeadlessClient() — funnel.navigate() will throw TagadaError('missing_account_id') without it. A checkout session must be loaded first (tagada.checkout.loadSession(...)). The SDK sources the cart, currency, customer email, and promotion code from that session.

React provider: TagadaHeadlessProvider only forwards accountId through the full config prop, not the individual named props. Pass config={{ storeId, accountId, environment }} if you need funnel navigation in React.

Quick Start

Vanilla JavaScript
React
CDN / Script Tag

import { createHeadlessClient } from '@tagadapay/headless-sdk';

const tagada = createHeadlessClient({
  storeId: 'store_abc123',
  accountId: 'acc_abc123',
  environment: 'production',
});

// 1. Load (or create) a checkout session — populates the cart.
await tagada.checkout.loadSession(checkoutToken, sessionToken);

// 2. Get a redirect URL into the funnel.
const { url } = await tagada.funnel.navigate({
  funnelId: 'fnlv2_abc123',
  stepId:   'step_abc123',
  returnUrl: 'https://merchant.com/thank-you',
});

// 3. Send the shopper there.
window.location.assign(url);

import {
  TagadaHeadlessProvider,
  useHeadlessClient,
} from '@tagadapay/headless-sdk/react';

function App() {
  return (
    <TagadaHeadlessProvider
      config={{
        storeId: 'store_abc123',
        accountId: 'acc_abc123',
        environment: 'production',
      }}
    >
      <BuyNowButton />
    </TagadaHeadlessProvider>
  );
}

function BuyNowButton() {
  const sdk = useHeadlessClient();

  const handleBuy = async () => {
    await sdk.checkout.loadSession(checkoutToken, sessionToken);
    const { url } = await sdk.funnel.navigate({
      funnelId: 'fnlv2_abc123',
      stepId:   'step_abc123',
      returnUrl: 'https://merchant.com/thank-you',
    });
    window.location.assign(url);
  };

  return <button onClick={handleBuy}>Buy now</button>;
}

<script src="https://cdn.jsdelivr.net/npm/@tagadapay/headless-sdk/dist/tagada-headless.min.js"></script>
<script>
  const tagada = TagadaHeadless.create({
    storeId: 'store_abc123',
    accountId: 'acc_abc123',
    environment: 'production',
  });

  await tagada.checkout.loadSession(checkoutToken, sessionToken);
  const { url } = await tagada.funnel.navigate({
    funnelId: 'fnlv2_abc123',
    stepId:   'step_abc123',
    returnUrl: 'https://merchant.com/thank-you',
  });

  window.location.assign(url);
</script>

What Happens Under the Hood

navigate() runs the same sequence the WooCommerce plugin does, with caching so repeat calls in the same page are cheap:

POST /api/v1/cms/session/anonymous — creates an anonymous CMS session, returns a token.
POST /api/v1/cms/session/v2/init — initializes the CMS session and binds a CMS customer id.
POST /api/v1/funnel/initialize — creates the funnel session for funnelId + stepId.
POST /api/v1/funnel/navigate — fires an INIT_CHECKOUT event with the cart and returns { url }.

The CMS token, session id, and customer id are cached on the module instance. Calling navigate() again in the same page skips steps 1–3.

`navigate()` Input Reference

Field	Type	Required	Notes
`funnelId`	`string`	yes	Funnel to enter (e.g. `fnlv2_xxx`).
`stepId`	`string`	yes	Funnel step to land on. Used for both `entryStepId` and `funnelStepId`.
`returnUrl`	`string`	no	Where the funnel should send the shopper back to after checkout.
`customer`	`{ email?, currency?, locale? }`	no	Overrides. Defaults to `session.customer.email` / `session.currency`.
`discountCodes`	`string[]`	no	Defaults to `[session.promotionCode]` if a promo is applied, otherwise none.
`metadata`	`Record<string, unknown>`	no	Arbitrary metadata forwarded to the funnel-navigate event and stored on the checkout session. Reserved key: `lockShippingRate` (see below).
`externalShipping`	`{ amount, currency }`	no	Shipping your storefront already settled on, in minor units. See below.
`currentUrl`	`string`	no	Page URL recorded by the funnel. Defaults to `globalThis.location?.href` in browsers.
`accountId`	`string`	no	Per-call override. Falls back to `HeadlessConfig.accountId`.

Carrying Your Own Shipping Amount

If your storefront already charges its own shipping, pass externalShipping so the shopper is charged the amount they agreed to instead of whatever rate the platform would auto-select:

await sdk.funnel.navigate({
  funnelId: 'fnlv2_xxx',
  stepId: 'step_xxx',
  externalShipping: { amount: 1200, currency: 'USD' }, // $12.00
});

The checkout session starts on a rate matching that exact amount — an existing rate if one matches, otherwise a dynamically created one.

Only send this once shipping is genuinely resolved. { amount: 0 } means free shipping and pins a free rate — it is not a stand-in for “not known yet”. While shipping is unresolved, omit the field entirely and the platform selects a rate as before.

Keeping your rate when the checkout re-evaluates shipping

The hosted checkout re-evaluates shipping rates when the page loads, when the shopper changes country, and when discount codes move the cart across a rate’s amount bracket. If the rate your storefront picked stops matching the store’s rate conditions — for example a “

10 under

150” rate on a cart whose catalogue price is $170 before the discount — the checkout swaps it for an eligible one. If your storefront is the authority on shipping, opt out of that re-selection by sending lockShippingRate: true in metadata alongside your pre-selected rate:

await sdk.funnel.navigate({
  funnelId: 'fnlv2_xxx',
  stepId: 'step_xxx',
  externalShipping: { amount: 1000, currency: 'USD' }, // $10.00
  metadata: { lockShippingRate: true },
});

With the lock set:

The checkout keeps the pre-selected rate on load, on country changes and on discount changes; it never auto-selects another one.
The shipping selector shows that single rate and the shopper cannot change it.
The lock only applies once a rate is actually on the session (externalShipping, or a later setShippingRate call). With no rate yet, the checkout behaves as if the flag were absent.

Leave the flag off when you want the platform’s own rate rules — brackets, country restrictions, highlighted rate — to drive the selection.

Return Value

{
  url: string;             // Redirect destination.
  funnelSessionId: string; // From /funnel/initialize, useful for logging/debugging.
}

The SDK does not perform the redirect — call window.location.assign(url), router.push(url), or whatever your framework uses.

Errors

funnel.navigate() throws typed TagadaErrors:

no_cart_loaded — sdk.checkout.loadSession(...) was not called first. The SDK has no cart to send.
missing_account_id — accountId was not provided on createHeadlessClient() and not passed per call.

Network and validation failures throw the standard TagadaNetworkError / TagadaValidationError.

SSR & Non-Browser Environments

The SDK reads globalThis.location?.href for currentUrl when running in a browser. In SSR / Node contexts, pass currentUrl explicitly:

await sdk.funnel.navigate({
  funnelId,
  stepId,
  currentUrl: 'https://merchant.com/products/foo',
  returnUrl: 'https://merchant.com/thank-you',
});

Because navigate() returns { url } rather than redirecting, it composes cleanly with SPA routers (react-router, next/router) and server-side handoffs.

Funnel navigation vs. checkout.createSessionUrl(): Use funnel.navigate() to enter a marketing funnel (pre-checkout steps, upsell sequencing). Use checkout.createSessionUrl() when you just need a self-hosted checkout URL with no funnel logic in front of it.

Overview

Payments

Web Integration

Tracking & Attribution

Node SDK

Funnels

Funnel demos

Examples

Shopify

WooCommerce

SaaS Billing

Headless SDK

Plugin SDK

Plugin CLI

Studio MCP (AI Agents)

Config MCP (AI Agents)

Hosting & A/B Testing

Internal

Funnel Navigation

Prerequisites

Quick Start

What Happens Under the Hood

`navigate()` Input Reference

Carrying Your Own Shipping Amount

Keeping your rate when the checkout re-evaluates shipping

Return Value

Errors

SSR & Non-Browser Environments

​Funnel Navigation

​Prerequisites

​Quick Start

​What Happens Under the Hood

​navigate() Input Reference

​Carrying Your Own Shipping Amount

​Keeping your rate when the checkout re-evaluates shipping

​Return Value

​Errors

​SSR & Non-Browser Environments

Funnel Navigation

Prerequisites

Quick Start

What Happens Under the Hood

`navigate()` Input Reference

Carrying Your Own Shipping Amount

Keeping your rate when the checkout re-evaluates shipping

Return Value

Errors

SSR & Non-Browser Environments