> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tagada.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkout Sessions

> Create pre-loaded cart links and manage checkout flows

# Checkout Sessions

Use `tagada.checkout.createSession` to build **pre-loaded checkout links**: cart line items, currency, and optional customer data are applied before the customer lands on your checkout page.

<Info>
  `createSession` follows the `/checkout/init` redirect and returns the final URL plus a `checkoutToken` (when available) without forcing the browser through the 302.
</Info>

***

## Create a basic session

```ts theme={null}
import Tagada from '@tagadapay/node-sdk';

const tagada = new Tagada('your-api-key');

const { redirectUrl, checkoutToken } = await tagada.checkout.createSession({
  storeId: 'store_...',
  items: [{ variantId: 'variant_...', quantity: 1 }],
  currency: 'USD',
  checkoutUrl: 'https://your-store.com/checkout',
});

// Share redirectUrl with the customer; persist checkoutToken if you need async status polling
```

| Field           | Description                                                        |
| --------------- | ------------------------------------------------------------------ |
| `redirectUrl`   | Fully qualified URL to open in the browser                         |
| `checkoutToken` | Token extracted from the URL when present (e.g. for `asyncStatus`) |

***

## Pre-fill customer data

Optional string fields are passed through to checkout init:

```ts theme={null}
await tagada.checkout.createSession({
  storeId: STORE_ID,
  items: [{ variantId, quantity: 1 }],
  currency: 'USD',
  checkoutUrl,
  customerEmail: 'jane@example.com',
  customerFirstName: 'Jane',
  customerLastName: 'Doe',
  customerPhone: '+15551234567',
});
```

***

## Customer tags for funnel routing

Attach tags so **funnel edge conditions** (e.g. `customer.hasTag`) can route the session:

```ts theme={null}
await tagada.checkout.createSession({
  storeId: STORE_ID,
  items: [{ variantId, quantity: 1 }],
  currency: 'USD',
  checkoutUrl,
  customerTags: ['vip', 'premium'],
});
```

<Tip>
  Combine explicit tags with URL/query enrichment where configured — see [Customer Management](/developer-tools/node-sdk/customers) for auto-enriched tags and tag-driven conditions.
</Tip>

***

## Async payment status (3DS redirects)

After a redirect-based flow (e.g. 3DS), poll session status with the token from `createSession`:

```ts theme={null}
const status = await tagada.checkout.asyncStatus(checkoutToken!);
```

<Note>
  `checkoutToken` may be `null` if it is not present on the redirect URL. Ensure `createSession` is used (not the deprecated `init` helper) so the client can parse the token reliably.
</Note>

***

## SDK methods reference

| Method                                       | Description                                                                     |
| -------------------------------------------- | ------------------------------------------------------------------------------- |
| `tagada.checkout.createSession(params)`      | Build query for `/checkout/init`, return `{ redirectUrl, checkoutToken }`       |
| `tagada.checkout.asyncStatus(checkoutToken)` | GET async status after redirects                                                |
| `tagada.checkout.pay(params)`                | Server-side pay for an existing session (`checkoutSessionId`, instrument, etc.) |
| `tagada.checkout.init(params)`               | **Deprecated** — prefer `createSession`                                         |

Common `createSession` params include `storeId`, `items`, `currency`, `checkoutUrl`, `returnUrl`, `locale`, `customerId`, `customerEmail`, `customerFirstName`, `customerLastName`, `customerPhone`, `customerTags`, `cartToken`, and `draft`.

***

## Next steps

<CardGroup cols={2}>
  <Card title="Upsell & downsell funnel" icon="arrow-up-right-dots" href="/developer-tools/node-sdk/upsell-downsell-funnel">
    Conditional routing after checkout using funnel edges
  </Card>

  <Card title="Customer management" icon="users" href="/developer-tools/node-sdk/customers">
    Tags, listing, and funnel conditions tied to customers
  </Card>

  <Card title="Merchant quick start" icon="rocket" href="/developer-tools/node-sdk/merchant-quickstart">
    End-to-end setup through a live checkout link
  </Card>

  <Card title="Step config guide" icon="sliders" href="/developer-tools/node-sdk/step-config-guide">
    Per-step checkout UI, scripts, and order bumps
  </Card>
</CardGroup>