---
name: bijection-polar
description: "Evaluate and integrate the Polar component with Bijection."
---

# Polar

Subscriptions and billing

- Package: @bijectionhq/polar
- Category: Payments
- Status: Preview
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/polar/tree/29621ba52e66074082bf2c5ada013c1e3023fd78
- Upstream: https://github.com/convex/polar/tree/4b7640a529108c2f06ab5fbf7105ff1fd040b21e
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/polar

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/polar.git
cd polar
git checkout 29621ba52e66074082bf2c5ada013c1e3023fd78
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes @convex-dev/polar. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses Polar. Follow the installation and configuration steps exactly.

# Polar

## Instructions

Integrates Polar subscriptions and billing into Convex applications with automatic webhook synchronization and React UI components. Provides type-safe subscription management, product syncing, and customer portal integration. Handles all Polar price types including fixed, custom pay-what-you-want, seat-based, and metered pricing models.

### Installation

```bash
npm install @convex-dev/polar
```

Current npm version: `@convex-dev/polar@0.9.2`

## Use cases

- **Add subscription billing to SaaS apps** - Configure products with keys like `premiumMonthly` and `premiumYearly`, then use `CheckoutLink` components for user upgrades
- **Implement tiered pricing with trials** - Support free trials, multiple subscription tiers, and seat-based pricing for team plans
- **Build customer self-service portals** - Let users manage subscriptions, update payment methods, and view billing history with `CustomerPortalLink`
- **Handle subscription lifecycle events** - Process webhook events like `subscription.updated` and `product.created` with type-safe handlers
- **Migrate from other billing providers** - Replace existing subscription logic while keeping product data synced between Polar and Convex

## How it works

The component creates a `Polar` client in your Convex backend that syncs product and subscription data via webhooks. You configure it with a `getUserInfo` function that maps your user system to Polar customers, and optionally define product keys for easy reference. The webhook handler at `/polar/events` keeps subscription data current by processing events like `subscription.created` and `product.updated`.

React components like `CheckoutLink` and `CustomerPortalLink` generate Polar URLs on-demand through Convex actions. The `CheckoutLink` supports embedded checkout or redirect modes, while `CustomerPortalLink` provides subscription management. Functions like `getCurrentSubscription` and `changeCurrentSubscription` handle subscription queries and modifications.

Product configuration supports static mapping (`products: { premiumMonthly: 'product_id' }`) or dynamic listing with `listAllProducts`. The component handles all Polar price types automatically, exposing different fields based on `amountType` - from simple `priceAmount` for fixed pricing to complex `seatTiers` for seat-based models.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Polar is not needed

## Resources

- [npm package](https://www.npmjs.com/package/%40convex-dev%2Fpolar)
- [GitHub repository](https://github.com/erquhart/convex-polar)
- [Live demo](https://github.com/get-convex/polar/tree/main/example)
- [Convex Components Directory](https://www.convex.dev/components/polar)
- [Convex documentation](https://docs.convex.dev)