> ## 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.
`createSession` follows the `/checkout/init` redirect and returns the final URL plus a `checkoutToken` (when available) without forcing the browser through the 302.
***
## 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`) |
| `checkoutRoutePublished` | `false` when no published checkout front-end could be found for the store — the redirect target most likely renders nothing and the merchant still has to publish and promote a funnel. `null` when we did not report on it (you supplied your own `checkoutUrl`, or the API predates the field). |
***
## 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'],
});
```
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.
***
## Discount codes + affiliate attributes
Use this when you build the checkout link **from your server** and the customer opens **Tagada hosted checkout** after adding items on your site. Apply a promo code and attach affiliate tracking in the same `createSession` call:
```ts theme={null}
const { redirectUrl, checkoutToken } = await tagada.checkout.createSession({
storeId: STORE_ID,
items: [{ variantId, quantity: 1 }],
currency: 'USD',
checkoutUrl: 'https://your-store.com/checkout',
discountCodes: ['SAVE10'],
metadata: {
cartCustomAttributes: [
{ name: 'affiliate_id', value: 'partner_42' },
],
},
customerMetadata: {
queryParams: '?ref=partner&utm_source=fb',
cookies: { _fbp: 'fb.1.1234567890' },
},
customerTags: ['affiliate'],
});
```
You can also pass `ref`, `utm_source`, and other query params as top-level fields — they are forwarded into `customerMetadata.queryParams` automatically when `customerMetadata` is omitted.
Custom attributes and query params appear on the resulting order (CRM → Order → Attributes) and in the `order/paid` webhook payload.
***
## 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!);
```
`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.
***
## SDK methods reference
| Method | Description |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `tagada.checkout.createSession(params)` | Build query for `/checkout/init`, return `{ redirectUrl, checkoutToken, checkoutRoutePublished }` |
| `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`, `discountCodes`, `metadata`, `customerMetadata`, `cartToken`, and `draft`.
***
## Next steps
Conditional routing after checkout using funnel edges
Tags, listing, and funnel conditions tied to customers
End-to-end setup through a live checkout link
Per-step checkout UI, scripts, and order bumps