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)

You can also create a session directly from the browser:

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

// session.checkoutUrl   -- Tagada-hosted checkout URL (for reference)
// session.checkoutToken -- token to use with loadSession()
// session.sessionToken  -- JWT for authenticated calls
// session.customerId    -- assigned customer ID

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

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
}

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 new session
`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

Web Integration

Tracking & Attribution

Node SDK

Funnels

Shopify

SaaS Billing

Headless SDK

Plugin SDK

Plugin CLI

Studio MCP (AI Agents)

CRM 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

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

​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

Shipping

React Hook

Full Hook API