Polar Typescript Sdk

Polar TypeScript SDK

Use the generated, versioned Polar SDK without inventing methods or parameters.

Inspect the application first

1. Identify the installed @polar-sh/sdk version and preserve the API version already selected by the application.
2. Inspect generated service signatures, model interfaces, response types, and endpoint-specific errors before writing calls.
3. Use createPolar for the full service client. Use createPolarCore with individual service functions when bundle size or tree-shaking matters.
4. Identify whether the access token is scoped to an organization. Pass organization_id when the selected token does not imply one, and confirm the required endpoint scopes.
5. Keep client, webhook, and environment configuration in trusted server-side code.

Migrate from the old SDK

Read Migration from the <1.0.0 SDK before changing an application that imports an unversioned Polar class or uses camelCase request and response fields. Do not mix old and new client, field-casing, pagination, error, or webhook conventions.

Configure and reuse the client

Keep production and sandbox access tokens separate. Never expose an organization access token in browser, mobile, or other public client code. Pass environment: "sandbox" while testing; omit it or pass environment: "production" in production.

import { createPolar } from "@polar-sh/sdk/{{ ir.versions[0].version }}";

const accessToken = process.env.POLAR_ACCESS_TOKEN;
if (!accessToken) {
  throw new Error("POLAR_ACCESS_TOKEN is required");
}

const polar = createPolar({
  accessToken,
  environment: "sandbox",
});

const customerState = await polar.customers.getStateExternal("usr_123");

Create the client once for a long-running server and reuse it. The TypeScript client uses fetch and does not expose a connection-closing lifecycle.

For tree-shakable individual functions, create a core client and bind only the operations the application uses:

import { createPolarCore } from "@polar-sh/sdk/{{ ir.versions[0].version }}";
import { getStateExternalCustomers } from "@polar-sh/sdk/{{ ir.versions[0].version }}/services/customers";

const polarCore = createPolarCore({ accessToken });
const getCustomerState = getStateExternalCustomers(polarCore);
const customerState = await getCustomerState("usr_123");

Follow generated argument and output conventions

• Use camelCase service names and methods such as benefitGrants, getStateExternal, and iterList.
• Keep request, query, and response field names in API-style snake_case, such as external_customer_id.
• Pass path parameters positionally.
• Pass query parameters as an optional object after path parameters.
• Pass request bodies as a single typed object.
• Treat responses as typed plain JavaScript objects.
• Expect UUID and date-time OpenAPI fields to remain strings.
• Consume paginated iter* methods with for await; each additional page performs another API request.

for await (const customer of polar.customers.iterList({
  sorting: ["email"],
})) {
  console.log(customer.id);
}

Correlate customers with stable external IDs

Use the application's immutable user or organization identifier as the Polar customer external_id. It is unique within a Polar organization. It may be assigned later when initially unset, but it cannot be changed or removed once set.

const customer = await polar.customers.create({
  external_id: "usr_123",
  email: "user@example.com",
});
const customerState = await polar.customers.getStateExternal("usr_123");

Handle concurrent creation safely. A preflight lookup followed by creation is not atomic; if creation reports an existing email or external ID, fetch and reconcile the existing customer rather than creating a second mapping.

Create checkout and customer portal sessions

Create checkout sessions on the server and send only the returned URL to the browser. Prefer external_customer_id so a completed checkout is reconciled with the application's customer.

const productId = process.env.POLAR_PRODUCT_ID;
if (!productId) {
  throw new Error("POLAR_PRODUCT_ID is required");
}

const checkout = await polar.checkouts.create({
  products: [productId],
  external_customer_id: "usr_123",
  success_url: "https://example.com/billing/success?checkout_id={CHECKOUT_ID}",
  return_url: "https://example.com/settings/billing",
});
redirect(checkout.url);

Do not treat the success redirect as proof of payment or entitlement. Confirm access through customer state or a verified webhook.

Create short-lived customer portal sessions only for an authenticated customer:

const session = await polar.customerSessions.create({
  external_customer_id: "usr_123",
  return_url: "https://example.com/settings/billing",
});
redirect(session.customer_portal_url);

Validate return URLs and never let an untrusted caller choose another customer's external ID.

Reconcile feature access from customer state

Prefer a feature_flag benefit attached to the relevant products over inferring access from subscription statuses. Reconcile both access grants and access revocations.

const benefitId = process.env.POLAR_BENEFIT_ID;
if (!benefitId) {
  throw new Error("POLAR_BENEFIT_ID is required");
}

const customerState = await polar.customers.getStateExternal("usr_123");
const enabled = customerState.granted_benefits.some(
  (grant) => grant.benefit_id === benefitId,
);

await setFeatureAccess({
  customerExternalId: "usr_123",
  enabled,
});

Make setFeatureAccess an idempotent application write. A missing benefit must disable access, not merely skip a grant operation.

For webhook-driven synchronization, use benefit-grant events for an incremental local grant ledger or customer.state_changed for complete snapshot reconciliation. Read Webhook processing before implementing or modifying a receiver.

Ingest metered usage events

Read Usage-event ingestion before implementing metered billing. In particular:

• Match the event name and metadata to the configured meter.
• Associate the event with exactly one customer_id or external_customer_id.
• Assign every logical event a stable, unique external_id.
• Reuse the same external_id when retrying so Polar can deduplicate the event.
• Inspect both inserted and duplicates in the ingestion result.
• Enforce usage limits in the application; ingestion does not reject an action because a customer has exhausted a balance.

Handle API failures intentionally

Handle generated endpoint-specific errors before broad SDK errors. Import base errors from @polar-sh/sdk and version-specific endpoint errors from the selected API version's errors namespace.

• PolarNetworkError: retry only when the operation is safe or carries a stable deduplication identifier.
• PolarRateLimitError: apply bounded backoff and honor retryAfter when present.
• PolarServerError: retry selected 5xx failures with bounded exponential backoff and jitter.
• PolarClientError: do not blindly retry authentication, authorization, validation, or not-found failures.

Never create a new usage-event external_id during a retry. For other mutations, use an endpoint-supported idempotency mechanism or application-level reconciliation before retrying.