@polar-sh/tanstack-start

Payments and Checkouts made dead simple with Tanstack Start

pnpm install @polar-sh/tanstack-start

Checkout

Create a Checkout handler which takes care of redirections.

// routes/api/checkout.ts
import { Checkout } from '@polar-sh/tanstack-start'
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/api/checkout')({
  server: {
    handlers: {
      GET: Checkout({
        accessToken: process.env.POLAR_ACCESS_TOKEN!,
        successUrl: process.env.SUCCESS_URL,
        returnUrl: 'https://myapp.com', // Optional Return URL, which renders a Back-button in the Checkout
        environment: 'sandbox', // Use sandbox if you're testing Polar - omit the parameter or pass 'production' otherwise
        theme: 'dark', // Enforces the theme - System-preferred theme will be set if left omitted
      }),
    },
  },
})

Query Params

Pass query params to this route.

• products ?products=123 - Repeat the parameter for multiple products: ?products=123&products=456
• customer_id (optional) ?products=123&customer_id=xxx
• external_customer_id (optional) ?products=123&external_customer_id=xxx
• customer_email (optional) ?products=123&[email protected]
• customer_name (optional) ?products=123&customer_name=Jane
• discount_code (optional) ?products=123&discount_code=SAVE20 - Apply a discount code before redirecting. Discount codes must be enabled; discount_id takes precedence when both are supplied.
• seats (optional) ?products=123&seats=5 - Number of seats for seat-based products
• metadata (optional) URL-Encoded JSON string

Customer IP Address

Unless customer_ip_address is passed, the customer's IP address is taken from the x-forwarded-for, x-real-ip or cf-connecting-ip header and sent to Polar to show local currency. Set customerIpAddress to a function (request) => ip to resolve it yourself, or to false to not send it.

Customer Portal

Create a customer portal where your customer can view orders and subscriptions.

// routes/api/portal.ts
import { CustomerPortal } from '@polar-sh/tanstack-start'
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/api/portal')({
  server: {
    handlers: {
      GET: CustomerPortal({
        accessToken: process.env.POLAR_ACCESS_TOKEN!,
        getCustomerId: async (request: Request) => '', // Function to resolve a Polar Customer ID
        returnUrl: 'https://myapp.com', // Optional Return URL, which renders a Back-button in the Customer Portal
        environment: 'sandbox', // Use sandbox if you're testing Polar - omit the parameter or pass 'production' otherwise
      }),
    },
  },
})

Webhooks

A simple utility which resolves incoming webhook payloads by verifying their signature with your webhook secret.

// routes/api/webhook/polar.ts
import { Webhooks } from '@polar-sh/tanstack-start'
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/api/webhook/polar')({
  server: {
    handlers: {
      POST: Webhooks({
        webhookSecret: process.env.POLAR_WEBHOOK_SECRET!,
        onPayload: async (payload) => {
          // Handle the payload
          // No need to return an acknowledge response
        },
      }),
    },
  },
})

Payload Handlers

The Webhook handler also supports granular handlers for easy integration.

• onPayload: (payload) => - Called for every event, in addition to the matching handler below
• onCheckoutCreated: (payload) =>
• onCheckoutExpired: (payload) =>
• onCheckoutUpdated: (payload) =>
• onOrderCreated: (payload) =>
• onOrderUpdated: (payload) =>
• onOrderPaid: (payload) =>
• onOrderRefunded: (payload) =>
• onRefundCreated: (payload) =>
• onRefundUpdated: (payload) =>
• onSubscriptionCreated: (payload) =>
• onSubscriptionUpdated: (payload) =>
• onSubscriptionActive: (payload) =>
• onSubscriptionCanceled: (payload) =>
• onSubscriptionCycled: (payload) =>
• onSubscriptionPastDue: (payload) =>
• onSubscriptionPaused: (payload) =>
• onSubscriptionResumed: (payload) =>
• onSubscriptionRevoked: (payload) =>
• onSubscriptionUncanceled: (payload) =>
• onProductCreated: (payload) =>
• onProductUpdated: (payload) =>
• onOrganizationUpdated: (payload) =>
• onBenefitCreated: (payload) =>
• onBenefitUpdated: (payload) =>
• onBenefitGrantCreated: (payload) =>
• onBenefitGrantCycled: (payload) =>
• onBenefitGrantUpdated: (payload) =>
• onBenefitGrantRevoked: (payload) =>
• onCustomerCreated: (payload) =>
• onCustomerUpdated: (payload) =>
• onCustomerDeleted: (payload) =>
• onCustomerStateChanged: (payload) =>
• onCustomerSeatAssigned: (payload) =>
• onCustomerSeatClaimed: (payload) =>
• onCustomerSeatRevoked: (payload) =>
• onDiscountCreated: (payload) =>
• onDiscountUpdated: (payload) =>
• onDiscountDeleted: (payload) =>
• onMemberCreated: (payload) =>
• onMemberUpdated: (payload) =>
• onMemberDeleted: (payload) =>

Handlers are async functions. Webhook payloads use the generated SDK's snake_case fields. Signed events unknown to the installed SDK version are acknowledged and ignored so newly introduced event types do not cause retries.