> ## 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.

# Headless SDK

> Use TagadaPay as a headless checkout and CRM backend from any website

# Headless SDK

Build your own store with **any framework** (React, Vue, Svelte, plain HTML) or **AI tools** (Lovable, Claude, v0) and use TagadaPay as the headless backend for checkout, payments, pixel tracking, and CRM.

<Info>
  **When to use this SDK:**

  * You're building a custom store on your own hosting (Vercel, Netlify, etc.)
  * You want full control over the UI while TagadaPay handles payments, PSP routing, pixel tracking, and subscriptions
  * An AI tool is generating your store code and needs a simple, self-documenting API

  **When NOT to use this SDK:**

  * You want to deploy pages **on TagadaPay** — use the [Plugin SDK](/developer-tools/sdk/introduction) instead
  * You only need a checkout link — use [Web Integration](/developer-tools/web-integration/trigger-checkout-from-website)
  * You need server-side automation — use the [Node SDK](/developer-tools/node-sdk/quick-start)
  * You're building a **payment platform that charges for many merchants** (Suby-style PSPs, marketplaces) — use the [Partners section](/developer-tools/partners/introduction) instead. Partner S2S deliberately avoids checkout sessions, which this SDK is built around.
</Info>

<Tip>
  **Not sure?** Compare all five SDKs side-by-side on [SDKs at a glance](/developer-tools/sdks-at-a-glance).
</Tip>

***

## How It Works

```
Your Store (Vercel, Netlify, etc.)
├── Frontend (any framework)
│   ├── @tagadapay/headless-sdk    ← checkout, pixel tracking, offers, CRM
│   └── @tagadapay/core-js         ← card tokenization, 3DS (optional)
└── Backend (API routes)
    └── @tagadapay/node-sdk         ← server automation, webhooks
```

The headless SDK talks to TagadaPay's REST API from the browser. It's a **single import** that gives you these modules:

| Module                | What it does                                                |
| --------------------- | ----------------------------------------------------------- |
| **`tagada.checkout`** | Load sessions, update cart, apply promos, handle shipping   |
| **`tagada.payment`**  | Discover APMs, tokenize cards, process payments, handle 3DS |
| **`tagada.offers`**   | Load upsells/downsells, accept/decline, order bumps         |
| **`tagada.catalog`**  | Browse products, variants, and prices                       |
| **`tagada.customer`** | Profile, orders, subscriptions                              |
| **`tagada.funnel`**   | Send shoppers into a TagadaPay funnel from your own cart    |

<Note>
  **Pixel tracking** (Meta, TikTok, Snap, GTM, GA4) is configured in the TagadaPay dashboard and automatically injected into your checkout sessions. See the [Pixels](/developer-tools/headless-sdk/pixels) page for details.
</Note>

***

## Install

```bash theme={null}
npm install @tagadapay/headless-sdk

# Optional: for client-side card tokenization
npm install @tagadapay/core-js
```

***

## Quick Start

<Tabs>
  <Tab title="Vanilla JavaScript">
    ```typescript theme={null}
    import { createHeadlessClient } from '@tagadapay/headless-sdk';

    const tagada = createHeadlessClient({
      storeId: 'store_abc123',
      environment: 'production',
    });

    // 1. Load checkout session (token from URL)
    const session = await tagada.checkout.loadSession(checkoutToken, sessionToken);

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

    // 3. Tokenize card + pay (3DS handled automatically)
    const { tagadaToken } = await tagada.payment.tokenizeCard({
      cardNumber: '4242424242424242',
      expiryDate: '12/28',
      cvc: '123',
    });

    const result = await tagada.payment.processPayment({
      checkoutSessionId: session.id,
      tagadaToken,
    });

    // 4. Handle result
    if (result.status === 'succeeded') {
      console.log('Paid!', result.order);
    } else if (result.status === 'requires_redirect') {
      window.location.href = result.redirectUrl;
    } else if (result.status === 'failed') {
      console.error(result.error);
    }
    ```
  </Tab>

  <Tab title="React">
    ```tsx theme={null}
    import {
      TagadaHeadlessProvider,
      useCheckout,
      usePayment,
    } from '@tagadapay/headless-sdk/react';

    function App() {
      return (
        <TagadaHeadlessProvider storeId="store_abc123" environment="production">
          <CheckoutPage />
        </TagadaHeadlessProvider>
      );
    }

    function CheckoutPage() {
      const { session, updateCustomer, updateAddress } = useCheckout(checkoutToken, sessionToken);
      const { processPayment, isProcessing, tokenizeCard } = usePayment({
        onPaymentSuccess: (result) => router.push('/thank-you'),
        onPaymentFailed: (result) => alert(result.error),
      });

      const handlePay = async () => {
        await updateCustomer({ email, firstName, lastName });
        await updateAddress({
          shippingAddress: { line1, city, postalCode, country },
        });

        const { tagadaToken } = await tokenizeCard({ cardNumber, expiryDate, cvc });
        await processPayment({ checkoutSessionId: session.id, tagadaToken });
        // 3DS redirects + polling handled automatically
        // onPaymentSuccess / onPaymentFailed callbacks fire when done
      };

      return (
        <button onClick={handlePay} disabled={isProcessing}>
          {isProcessing ? 'Processing...' : 'Pay Now'}
        </button>
      );
    }
    ```
  </Tab>

  <Tab title="CDN / Script Tag">
    ```html theme={null}
    <script src="https://cdn.jsdelivr.net/npm/@tagadapay/headless-sdk/dist/tagada-headless.min.js"></script>
    <script>
      const tagada = TagadaHeadless.create({
        storeId: 'store_abc123',
        environment: 'production',
      });

      // Use tagada.checkout, tagada.payment, etc.
    </script>
    ```
  </Tab>
</Tabs>

***

## SDK Layers — Which Package Does What?

TagadaPay has three npm packages. Most developers only need the Headless SDK:

| Package                       | Runs in          | Purpose                                                                                                                                                  |
| ----------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`@tagadapay/headless-sdk`** | Browser          | Checkout sessions, payments (tokenize + charge + 3DS), offers, CRM, catalog. **This is the main package.**                                               |
| **`@tagadapay/core-js`**      | Browser          | Low-level card tokenization, 3DS modal, Apple/Google Pay. **Optional peer dep** of headless-sdk — install it if you use `tagada.payment.tokenizeCard()`. |
| **`@tagadapay/node-sdk`**     | Server (Node.js) | Server automation: create stores, products, payment flows, webhooks, deploy to CDN, manage subscriptions.                                                |

```
┌───────────────────────────────────────────────────────────┐
│  Your Frontend (React, Vue, Svelte, HTML)                 │
│                                                           │
│  @tagadapay/headless-sdk                                  │
│    ├── checkout   — sessions, cart, promos, shipping      │
│    ├── payment    — processPayment(), 3DS, APMs, express  │
│    │   └── uses @tagadapay/core-js internally             │
│    ├── offers     — upsells, downsells, order bumps       │
│    ├── customer   — profile, orders, subscriptions        │
│    └── catalog    — products, variants, prices            │
│                                                           │
│  @tagadapay/core-js  (optional)                           │
│    └── tokenizeCard(), useThreeds(), Apple/Google Pay     │
└───────────────────────────────────────────────────────────┘
                        │ HTTPS
                        ▼
┌───────────────────────────────────────────────────────────┐
│  Your Backend (optional)                                  │
│  @tagadapay/node-sdk — stores, webhooks, deploy, etc.    │
└───────────────────────────────────────────────────────────┘
```

<Tip>
  **When do you need `@tagadapay/core-js` separately?** Only if you're building a [low-level payment integration](/developer-tools/payments/headless-payments) (mobile apps, embedded forms, MIT charges) without the Headless SDK's session management. If you use `@tagadapay/headless-sdk`, just `npm install @tagadapay/core-js` as a peer dep — the Headless SDK calls it internally.
</Tip>

***

## Design Principles

1. **Zero dependencies** — core uses native `fetch`. No axios, no lodash.
2. **AI-first** — single import, minimal config, self-contained methods. LLMs generate working code on the first try.
3. **Full payment coverage** — same APMs, express checkout, 3DS, and PSP routing as the Plugin SDK.
4. **Automatic 3DS** — `processPayment()` handles redirects, iframe challenges, and polling out of the box.
5. **Tree-shakeable** — unused modules are eliminated by bundlers.
6. **TypeScript-first** — full type coverage, JSDoc on every method.

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Build a Store with AI" icon="wand-magic-sparkles" href="/developer-tools/headless-sdk/build-store-with-ai">
    Use Claude or Lovable to generate a storefront — TagadaPay handles the rest
  </Card>

  <Card title="Payment Setup" icon="credit-card" href="/developer-tools/headless-sdk/payment-setup">
    Discover APMs, express checkout, and payment flows
  </Card>

  <Card title="Checkout Flow" icon="cart-shopping" href="/developer-tools/headless-sdk/checkout-flow">
    Sessions, cart, promo codes, and shipping
  </Card>

  <Card title="Funnel Navigation" icon="route" href="/developer-tools/headless-sdk/funnel-navigation">
    Send shoppers into a TagadaPay funnel from your own cart
  </Card>

  <Card title="Emails" icon="envelope" href="/developer-tools/headless-sdk/emails">
    Transactional emails — order confirmations, subscription receipts, cart recovery
  </Card>

  <Card title="Pixels" icon="bullseye-pointer" href="/developer-tools/headless-sdk/pixels">
    Client-side pixel tracking for Meta, TikTok, GA4, GTM, and more
  </Card>

  <Card title="Upsells & Offers" icon="arrow-up-right-dots" href="/developer-tools/headless-sdk/offers">
    Post-purchase offers and order bumps
  </Card>

  <Card title="Catalog" icon="store" href="/developer-tools/headless-sdk/catalog">
    Browse products, variants, and prices
  </Card>

  <Card title="Customer" icon="user" href="/developer-tools/headless-sdk/customer">
    Profiles, order history, and subscriptions
  </Card>
</CardGroup>