Checkout Flow

Manage checkout sessions, cart, promo codes, and shipping

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.

```typescript theme={null} // 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:

```typescript theme={null}
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

```typescript theme={null} 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.

```typescript theme={null}
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.

typescript theme={null} // 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', }, });

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

typescript theme={null} // 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:

```typescript theme={null} 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', }, });

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

***

## Promo Codes

```typescript theme={null}
// 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

```typescript theme={null} // 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);

<Tip>
  For **digital products**, skip shipping entirely — go straight from `updateAddress()` to payment.
</Tip>

***

## React Hook

```tsx theme={null}
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