Polar for polar

Documentation Index

Fetch the complete documentation index at: https://handbook.polar.sh/llms.txt

Use this file to discover all available pages before exploring further.

​

Summary

​

Goals

• Use Polar’s own APIs (customers, subscriptions, members, events) to manage our billing relationship with organizations.
• Track organization membership via the Polar member model so members have access to the customer portal.
• Meter event ingestion per organization for future usage-based billing.
• Receive webhooks from Polar to sync state changes back.
• All changes are safe to deploy incrementally — no big bang migration.
• Introduce paid plans for lower transaction fees and better support.

​

Non-Goals

• Replacing existing internal analytics (Tinybird, PostHog). Metering is for billing, not observability.

​

Key Concepts

• “Our Polar org”: The Polar organization that owns the customers, plans, and benefits we use to bill everyone else. Configured via POLAR_ORGANIZATION_ID.
• external_customer_id: We don’t store a Polar customer ID on the Organization model. Every Polar API call and incoming webhook identifies the customer by external_customer_id = str(org.id).
• external_id on members: User UUIDs become external_id on Polar members.
• Recursion guard: Two places stop the self org from billing itself — the metering cron excludes it when counting events, and enqueue_track_organization_review_usage short-circuits when the external customer is the self org.

​

Architecture

​

Mapping

​

Webhooks

​

Endpoint

router = APIRouter(
    prefix="/integrations/polar",
    tags=["integrations_polar"],
    include_in_schema=False,
)

@router.post("/webhook", status_code=202)
async def webhook(
    request: Request,
    session: AsyncSession = Depends(get_db_session),
) -> None:
    # Verify signature using standardwebhooks
    # Parse event type from payload
    # Enqueue via external_event_service.enqueue(
    #     session, ExternalEventSource.polar, task_name, event_id, data
    # )

​

ExternalEvent Integration

class PolarSelfEvent(ExternalEvent):
    source: Mapped[Literal[ExternalEventSource.polar]] = mapped_column(
        use_existing_column=True, default=ExternalEventSource.polar
    )
    __mapper_args__ = {
        "polymorphic_identity": ExternalEventSource.polar,
        "polymorphic_load": "inline",
    }

​

Webhook Handlers

IMPLEMENTED_WEBHOOKS = {
    "benefit_grant.created",
    "benefit_grant.updated",
    "benefit_grant.revoked",
    "order.created",
}

@actor(actor_name="polar_self.webhook.benefit_grant.created", priority=TaskPriority.LOW)
async def webhook_benefit_grant_created(event_id: uuid.UUID) -> None:
    async with AsyncSessionMaker() as session:
        async with external_event_service.handle(
            session, ExternalEventSource.polar, event_id
        ) as event:
            payload = WebhookBenefitGrantCreatedPayload.model_validate(event.data)
            await polar_self.handle_benefit_grant_event(session, payload)

​

API Surface

• GET /organizations/{id}/plans — list available paid plans
• GET /organizations/{id}/subscription — current subscription (or the synthesized free plan)
• POST /organizations/{id}/subscription — start a checkout for a plan
• PATCH /organizations/{id}/subscription — change plan, with proration depending on direction
• DELETE /organizations/{id}/subscription — cancel at period end

• GET /organizations/{id}/orders — list orders for the customer
• GET /organizations/{id}/orders/{order_id}/invoice — get an invoice download URL

• GET /organizations/{id}/billing-details
• PATCH /organizations/{id}/billing-details

• GET /organizations/{id}/payment-methods
• DELETE /organizations/{id}/payment-methods/{payment_method_id}
• POST /organizations/{id}/payment-methods/{payment_method_id}/default — set default

• POST /organizations/{id}/customer-session — short-lived token for the customer portal endpoints

​

Subscriptions

1. We were granting a lot of benefits unnecessarily which overwhelmed the system.
2. If everyone is always on a subscription it makes it more difficult to track subscription growth and cancellations.

​

Meter

​

Initial plan

​

Alternative suggestion

• Use debounce on polar_self.track_event_ingestion so that we don’t trigger new tracking tasks until the last one has been processed.
• Have a cron job that goes through the events ingested since last ingestion and trigger a polar_self.track_event_ingestion for those.

​

Implementation

1. Config + Integration Module — Add POLAR_* settings, move polar-sdk to regular deps, and scaffold a PolarSelfService singleton with no-op methods that early-return when unconfigured. No behavioral change.
2. Customer on Org Signup — On organization creation, enqueue a background task to create a Polar customer (keyed by org ID). Includes a backfill script for existing orgs. (We initially also created a free-tier subscription here, but dropped it — the free plan is synthesized client-side instead.)
3. Members — Sync UserOrganization add/remove to Polar members on the customer via background tasks. Backfill extended to cover existing memberships.
4. Metering Event Ingestion — Hook the ingested events to be bundled and ingested into into our own Polar organization with a count for the number of events ingested.
5. Receive Polar Webhooks — Add /integrations/polar/webhook endpoint with signature verification, plus a polar ExternalEventSource enum value and handlers for benefit_grant.* and order.created events.
6. Paid Plans — Wire checkout, plan changes (with proration), cancellation, the customer portal proxy methods (payment methods, billing details, customer session), and order/invoice listing. Benefits drive fees and support tier via the webhook handler in step 5.