Polar TypeScript SDK

The WebhookSubscriptionUpdatedPayload is sent whenever a subscription is updated. This event is a catch-all for all changes to a subscription, including renewals.

Choosing the right event

Depending on your use case, you may want to listen to more specific events instead of the general update event:

• Specific status changes: Listen to subscription.active, subscription.canceled, subscription.past_due, or subscription.revoked.
• Renewals: To specifically track renewals, listen to order.created events and inspect the billing_reason field.

Integrations

• Discord & Slack: These integrations support cancellation, past due, and revocation events. Note that renewals are skipped for these integrations.

import { WebhookSubscriptionUpdatedPayload } from "@polar-sh/sdk/models/components/webhooksubscriptionupdatedpayload.js";

let value: WebhookSubscriptionUpdatedPayload = {
  type: "subscription.updated",
  timestamp: new Date("2025-09-20T20:10:21.776Z"),
  data: {
    // ... subscription data
  }
};

A BalanceRefundEvent is an event generated by Polar whenever an order is refunded. It contains details about the refund, the associated customer, and the organization that owns the event. This model is useful for synchronizing refund states in your own system or triggering post-refund workflows.

import { BalanceRefundEvent } from "@polar-sh/sdk/models/components/balancerefundevent.js";

// Example of a BalanceRefundEvent object structure
let value: BalanceRefundEvent = {
  id: "<value>",
  timestamp: new Date("2024-02-22T00:39:19.003Z"),
  organizationId: "1dbfc517-0bbf-4301-9ba8-555ca42b9737",
  customerId: "<value>",
  customer: {
    id: "992fae2a-2a17-4b7a-8d9e-e287cf90131b",
    // ... other customer fields
  },
  externalCustomerId: null,
  label: "<value>",
  source: "system",
  name: "balance.refund",
  metadata: {
    transactionId: "<id>",
    refundId: "<id>",
    amount: 231482,
    currency: "Denar",
    // ... other metadata fields
  },
};

The BenefitGrantLicenseKeysWebhook is a data structure used in webhooks to notify systems when license keys are granted or revoked as a benefit. It contains details about the grant status, the associated customer, the member involved, and the specific benefit being provided.

Key properties include:

• isGranted and isRevoked: Boolean flags indicating the current state of the benefit.
• subscriptionId and orderId: Identifiers for the transaction that triggered the grant.
• benefit: Details about the license key benefit being issued.
• customer and member: Information about the entities receiving the benefit.

import { BenefitGrantLicenseKeysWebhook } from "@polar-sh/sdk/models/components/benefitgrantlicensekeyswebhook.js";

let value: BenefitGrantLicenseKeysWebhook = {
  createdAt: new Date("2024-03-27T04:10:14.057Z"),
  modifiedAt: new Date("2026-11-09T06:34:32.498Z"),
  id: "<value>",
  isGranted: true,
  isRevoked: false,
  subscriptionId: null,
  orderId: "<value>",
  customerId: "<value>",
  benefitId: "<value>",
  customer: {
    id: "992fae2a-2a17-4b7a-8d9e-e287cf90131b",
    // ... other customer fields
  },
  member: {
    id: "<value>",
    // ... other member fields
  },
  benefit: {
    id: "<value>",
    type: "license_keys",
    // ... other benefit fields
  },
  properties: {},
};

For optimal bundle size and tree-shaking performance, use the standalone function versions of API methods instead of the main Polar class. This requires using PolarCore instead of Polar.

Example: Standalone checkEmailUpdate

import { PolarCore } from "@polar-sh/sdk/core.js";
import { customerPortalCustomersCheckEmailUpdate } from "@polar-sh/sdk/funcs/customerPortalCustomersCheckEmailUpdate.js";

const polar = new PolarCore();

async function run() {
  const res = await customerPortalCustomersCheckEmailUpdate(polar, {
    token: "<value>",
  });
  if (res.ok) {
    const { value: result } = res;
  } else {
    console.log("customerPortalCustomersCheckEmailUpdate failed:", res.error);
  }
}

run();

Example: Standalone verifyEmailUpdate

import { PolarCore } from "@polar-sh/sdk/core.js";
import { customerPortalCustomersVerifyEmailUpdate } from "@polar-sh/sdk/funcs/customerPortalCustomersVerifyEmailUpdate.js";

const polar = new PolarCore();

async function run() {
  const res = await customerPortalCustomersVerifyEmailUpdate(polar, {
    token: "<value>",
  });
  if (res.ok) {
    const { value: result } = res;
    console.log(result);
  } else {
    console.log("customerPortalCustomersVerifyEmailUpdate failed:", res.error);
  }
}

run();