Polar Checkout API

This is the most reliable Polar integration. Talivia receives the same session ID in the signed order.paid webhook and can attribute the order without depending on a return visit.

Send the Talivia session to your backend

Browser checkout handoff

const sessionId = window.talivia.getSessionId();

const response = await fetch('/api/create-polar-checkout', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ sessionId }),
});

const { url } = await response.json();
window.location.assign(url);

The session ID is an attribution identifier, not authentication. Validate the product and signed-in user on your backend as usual.

Add metadata when checkout is created

Keep the Polar access token on the server. Polar copies checkout metadata to the resulting order and subscription, so one field covers both one-time and recurring products.

Create a Polar Checkout Session

import { Polar } from '@polar-sh/sdk';

const polar = new Polar({
  accessToken: process.env.POLAR_ACCESS_TOKEN,
});

const checkout = await polar.checkouts.create({
  products: [process.env.POLAR_PRODUCT_ID],
  successUrl:
    'https://your-site.com/thanks?checkout_id={CHECKOUT_ID}',
  returnUrl: 'https://your-site.com/pricing',
  externalCustomerId: user.id,
  customerEmail: user.email,
  metadata: {
    talivia_session_id: sessionId,
  },
});

return Response.json({ url: checkout.url });

externalCustomerId should be a stable ID from your own application. It gives Talivia a second matching signal for future renewals. Keep checkout_id={CHECKOUT_ID} in the success URL as a useful fallback and debugging signal.