Polar Integration

Polar is a merchant of record for developers. When you connect Polar to Holdify, subscription changes are automatically synced so your API key verifications always reflect the customer's current plan.

Setup

# Events Holdify listens for:
- order.created
- subscription.created
- subscription.updated
- subscription.canceled
- subscription.revoked
- benefit.granted
- benefit.revoked

How it works

1. 1 Customer subscribes or upgrades via Polar Checkout or Customer Portal
2. 2 Polar sends a webhook to Holdify with the subscription details
3. 3 Holdify verifies the webhook signature and dedupes by event ID
4. 4 Entitlements and limits are updated for the tenant
5. 5 The next /v1/verify call reflects the new plan

Entitlement mapping

Polar Benefits map directly to Holdify entitlements. Create Benefits in Polar and they'll appear in the entitlements array when you verify a key.

// In Polar, create Products with Benefits
// Holdify maps these to entitlements:

Product: "Pro Plan" ($29/mo)
├── Benefit: "API Access"      → entitlement: "api"
├── Benefit: "Chat Feature"    → entitlement: "chat"
└── Benefit: "Embeddings"      → entitlement: "embeddings"

Product: "Business Plan" ($99/mo)
├── Benefit: "API Access"      → entitlement: "api"
├── Benefit: "Chat Feature"    → entitlement: "chat"
├── Benefit: "Embeddings"      → entitlement: "embeddings"
├── Benefit: "Fine-tuning"     → entitlement: "fine-tuning"
└── Benefit: "Priority Support"→ entitlement: "priority-support"

Webhook payload

Holdify receives webhook payloads from Polar and processes them automatically. For reference, here's an example payload:

// Example: subscription.created webhook
{
  "type": "subscription.created",
  "data": {
    "id": "sub_123",
    "customer_id": "cust_456",
    "product_id": "prod_789",
    "status": "active",
    "current_period_start": "2025-01-01T00:00:00Z",
    "current_period_end": "2025-02-01T00:00:00Z"
  }
}

Handling cancellations

When a subscription is canceled or revoked:

• Entitlements are removed immediately
• Existing API keys can optionally be disabled
• The change is logged in the audit trail

Configure cancellation behavior in Settings → Integrations → Polar → On Cancel.

Next steps