Checkout Flow

The checkout module manages the full session lifecycle — load a session, update the cart, apply promo codes, and handle shipping.

Load a Checkout Session

A checkout session is typically created by the Node SDK on your server, then the token is passed to the frontend via URL parameter.

// Token from URL: /checkout?checkoutToken=ct_abc123&token=eyJ...
const checkoutToken = new URLSearchParams(window.location.search).get('checkoutToken');
const sessionToken = new URLSearchParams(window.location.search).get('token');

const session = await tagada.checkout.loadSession(checkoutToken, sessionToken);

// session.id          -- session ID (use for all subsequent calls)
// session.items       -- line items in the cart
// session.totals      -- subtotal, discount, shipping, tax, total
// session.customer    -- customer info if available
// session.currency    -- session currency (USD, EUR, etc.)

Create a Checkout Session (Client-Side)

From a landing / cart page, create a session and send the shopper to your checkout. Pin the variant you sell — do not pick “whatever is in the catalog”:

const { url } = await tagada.checkout.createSessionUrl({
  items: [{ variantId: 'var_xxx', quantity: 1 }],
  checkoutPath: '/checkout',
  // Page that hosts usePayment / maybeResumeFromUrl — 3DS returns here.
  returnUrl: 'https://mystore.com/checkout',
});
window.location.href = url; // your origin, not checkoutUrl
// → https://yoursite.com/checkout?checkoutToken=...&sessionToken=...

On /checkout, read both query names (sessionToken from createSessionUrl, token from a Tagada-hosted redirect):

const tokens = tagada.checkout.parseTokensFromUrl();
if (!tokens) {
  window.location.href = '/';
}
const session = await tagada.checkout.loadSession(tokens.checkoutToken, tokens.sessionToken);

createSession() is the same call without building the URL. It also returns checkoutUrl — that one is the Tagada-hosted checkout, not your page.

const created = await tagada.checkout.createSession({
  items: [{ variantId: 'var_xxx', quantity: 1 }],
  currency: 'USD',
  returnUrl: 'https://mystore.com/checkout',
});

// created.checkoutToken / created.sessionToken — load this session on YOUR page
// created.checkoutUrl — Tagada-hosted URL. Do NOT redirect here when self-hosting.

Headless cannot set checkoutUrl. It is generated by Tagada (plugin domain, funnel, or store-unavailable). On a self-hosted checkout, stay on your page and call loadSession(). To hop from a cart page to your own checkout path, use createSessionUrl() as above.

Update Cart

const updated = await tagada.checkout.updateCart(session.id, [
  { variantId: 'var_xxx', quantity: 2 },
  { variantId: 'var_yyy', quantity: 1 },
]);
// updated.totals reflects the new cart

Customer & Address

The SDK uses a two-step pattern: first set customer identity, then set the address. Under the hood, both are sent in a single atomic API call when updateAddress() is called.

Set Customer Info

updateCustomer() stores email, name, and phone in memory. No API call is made yet — the data is sent together with the address in the next step.

await tagada.checkout.updateCustomer(session.id, {
  email: 'jane@example.com',
  firstName: 'Jane',
  lastName: 'Doe',
  phone: '+33612345678',
});

Set Address

updateAddress() sends customer info + address together in one atomic API call. The customer’s firstName, lastName, and phone are automatically included in the address fields.

Shipped Product
Digital Product
Separate Billing

// Billing defaults to shipping automatically
await tagada.checkout.updateAddress(session.id, {
  shippingAddress: {
    line1: '123 Main St',
    city: 'San Francisco',
    state: 'CA',
    postalCode: '94102',
    country: 'US',
  },
});

// No shipping needed — just billing country for tax calculation
await tagada.checkout.updateAddress(session.id, {
  billingAddress: {
    country: 'US',
  },
});

// Different billing and shipping addresses
await tagada.checkout.updateAddress(session.id, {
  shippingAddress: {
    line1: '123 Main St',
    city: 'San Francisco',
    postalCode: '94102',
    country: 'US',
  },
  billingAddress: {
    line1: '456 Oak Ave',
    city: 'New York',
    postalCode: '10001',
    country: 'US',
  },
});

Combined Method

If you prefer a single explicit call:

await tagada.checkout.updateCustomerAndAddress(session.id, {
  customer: {
    email: 'jane@example.com',
    firstName: 'Jane',
    lastName: 'Doe',
  },
  shippingAddress: {
    line1: '123 Main St',
    city: 'San Francisco',
    postalCode: '94102',
    country: 'US',
  },
});

Address fields: firstName, lastName, phone can be passed directly in the address object too — they override the values from updateCustomer().

// Apply
await tagada.checkout.applyPromoCode(session.id, 'SAVE20');

// Remove
await tagada.checkout.removePromoCode(session.id);

// Reload session to see updated totals
const updated = await tagada.checkout.loadSession(checkoutToken, sessionToken);
console.log(updated.totals.discount); // discount amount in cents

What each total means

All amounts are in minor units (cents) in totals.currency.

Field	Meaning
`subtotal`	Line items before any promotion. An order-level promotion (e.g. “$5 off”) does not change it — look at `discount`.
`discount`	Total promotion amount applied to the order, as a positive number.
`shipping`	Selected shipping rate (`0` when none is selected or it is free).
`tax`	Tax, computed on the discounted base.
`total`	What the customer is charged: `subtotal − discount + shipping + tax`.

total is the same number the hosted checkout shows and the order is charged for — do not recompute it client-side.

Shipping

// Get available rates (requires address to be set first)
const rates = await tagada.checkout.getShippingRates(session.id);
// [{ id: 'rate_xxx', name: 'Standard', amount: 499, estimatedDays: 5 }]

// Select a rate
await tagada.checkout.selectShippingRate(session.id, rates[0].id);

For digital products, skip shipping entirely — go straight from updateAddress() to payment.

React Hook

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

function CheckoutPage() {
  const {
    session,
    isLoading,
    error,
    refresh,
    createSession,
    updateCart,
    updateCustomer,
    updateAddress,
    applyPromo,
    removePromo,
    getShippingRates,
    selectShippingRate,
  } = useCheckout(checkoutToken, sessionToken);

  // All methods auto-refresh the session after completion
}

On a landing page there is no token yet — pass null and use createSessionUrl on the CTA:

import { useCheckout, parseTokensFromUrl } from '@tagadapay/headless-sdk/react';

function LandingPage() {
  const { createSessionUrl } = useCheckout(null);

  async function buyNow() {
    const { url } = await createSessionUrl({
      items: [{ variantId: 'variant_xxx', quantity: 1 }],
      checkoutPath: '/checkout',
    });
    window.location.href = url;
  }

  return <button onClick={buyNow}>Buy now — $29.99</button>;
}

function CheckoutPage() {
  // The tokens arrive in the URL from the landing redirect
  const tokens = parseTokensFromUrl();
  const { session } = useCheckout(tokens?.checkoutToken, tokens?.sessionToken);
  // ...
}

Full Hook API

Method	Description
`session`	Current checkout session (null until loaded)
`isLoading`	True during any async operation
`error`	Last error, if any
`refresh()`	Reload the session
`createSession({ items, currency, returnUrl? })`	Create a session and load it in place (same page)
`createSessionUrl({ items, checkoutPath? })`	Create a session and get a redirect URL to your `/checkout` page — use on the landing CTA, then `window.location.href = url`
`updateCart(items)`	Replace cart items
`updateCustomer({ email, firstName, lastName, phone })`	Store customer identity (in memory)
`updateAddress({ shippingAddress?, billingAddress? })`	Set addresses + persist customer data (single API call)
`applyPromo(code)`	Apply a promo code
`removePromo(promotionId?)`	Remove a promo code
`getShippingRates()`	Fetch available shipping rates
`selectShippingRate(rateId)`	Select a shipping rate

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

Checkout Flow

Checkout Flow

Load a Checkout Session

Create a Checkout Session (Client-Side)

Update Cart

Customer & Address

Set Customer Info

Set Address

Combined Method

What each total means

Shipping

React Hook

Full Hook API

​Checkout Flow

​Load a Checkout Session

​Create a Checkout Session (Client-Side)

​Update Cart

​Customer & Address

​Set Customer Info

​Set Address

​Combined Method

​Promo Codes

​What each total means

​Shipping

​React Hook

​Full Hook API

Checkout Flow

Load a Checkout Session

Create a Checkout Session (Client-Side)

Update Cart

Customer & Address

Set Customer Info

Set Address

Combined Method

Promo Codes

What each total means

Shipping

React Hook

Full Hook API