Skip to content
Shoppable Developers

Authentication

Shoppable uses a two-token model, similar to Stripe.

1. Publishable token

Issued per cart/connector and prefixed pk_live_ or pk_test_. It is safe to ship in a browser bundle. You initialize the SDK with it:

const checkout = new ShoppableCheckout({ token: "pk_live_…" });

2. Session token (managed for you)

GET /cart-configuration validates your publishable token and origin, then mints a short-lived (1 day) session token returned as config.token. The SDK captures it automatically and attaches it as a Bearer credential to every checkout mutation — you never handle it directly.

Existing integrations

If your app already holds a minted session token (for example persisted in your own store), inject it so the SDK skips the initial handshake. Pass the publishable token as well and the SDK will transparently re-mint and retry if the session expires mid-checkout — so long-lived carts keep working without a 401.

const checkout = new ShoppableCheckout({
  token: "pk_live_…",            // enables auto-refresh on expiry
  sessionToken: storedToken,      // used immediately, no extra round-trip
  onSessionToken: (t) => persist(t), // fired whenever a token is minted/refreshed
});


checkout.getSessionToken(); // read the current token at any time

If you inject only a sessionToken (no publishable token), the SDK uses it as-is but cannot refresh it — an expired session surfaces as a 401.

Origin requirement

Every request must send an origin that matches your cart’s allowlist.

  • Browser: derived automatically from the page.

  • Node: pass an allowlisted origin:

    new ShoppableCheckout({ token, origin: "https://your-store.com" });