@polar-sh/nextjs

Payments and Checkouts made dead simple with Next.js.

pnpm install @polar-sh/nextjs

Checkout

Create a Checkout handler which takes care of redirections.

// checkout/route.ts
import { Checkout } from '@polar-sh/nextjs'

export const 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.

// portal/route.ts
import { CustomerPortal } from '@polar-sh/nextjs'
import type { NextRequest } from 'next/server'

export const GET = CustomerPortal({
  accessToken: process.env.POLAR_ACCESS_TOKEN!,
  getCustomerId: async (req: NextRequest) => '', // 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
})

If you identify customers by your own user ID, pass getExternalCustomerId instead of getCustomerId.

Webhooks

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

// api/webhook/polar/route.ts
import { Webhooks } from '@polar-sh/nextjs'

export const 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.