Polar subscriptions and renewals

Preserve attribution across Polar subscription creation, lifecycle changes, and recurring orders.

Talivia listens for Polar subscription lifecycle events and records paid renewal orders from order.paid. The first checkout should carry both a Talivia session ID and a stable application customer ID.

Create a recurring checkout

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

Polar copies checkout metadata to the created subscription. Talivia stores the subscription state and reuses the customer identity for later orders where there is no new browser session.

Identify signed-in customers

Call identify after login and again when you learn the Polar customer ID.

Link the Polar customer

window.talivia.identify(user.id, {
  email: user.email,
  externalCustomerId: user.id,
  providerName: 'polar',
  polarCustomerId: polarCustomer.id,
});

The external ID is usually enough when you set the same value during checkout. Adding the Polar customer ID makes matching more resilient.

What Talivia imports

the initial paid order and later paid renewals;
cumulative full or partial refunds;
subscription creation and status changes;
active subscription context during the initial connection backfill.

Trials without a paid order are stored as subscription state, not revenue.