​

Merchant Migrations to Polar

​

Summary

• Catalog and data import: products, benefits, discounts, and customers. This should be as automatic as possible.
• Payment methods: moving the payment methods is the hard part. We can use one of two Stripe mechanisms, PAN Copy or PAN Import; which one depends on the merchant’s current billing provider.

​

Background

​

Acronyms

• PM: payment methods
• PAN: Primary Account Number (the raw card number); regulated information.

​

Goals

• Migrate products, customers, subscriptions, and payment methods with minimal merchant effort.
• Surface incompatibility issues as an automatic precheck.
• Guarantee correct billing, pricing, trials, billing dates, etc.
• Minimize churn, e.g. avoid asking customers to re-enter their card details.

​

Non-goals

• Introduce new billing methods as part of the subscription. If we cannot support the migration, we should flag it.

​

Migration process

​

Moving cards: copy vs import

1. PAN Copy: the card already lives in the merchant’s Stripe account, and Stripe provides a feature to copy Customers and Payment Methods from one Stripe account to another. This is self-served by the merchant and “fast”, from a couple of hours to a few days depending on volume.
2. PAN Import: the card lives in another billing provider. The merchant, their current provider, Stripe, and us need to sync on what data moves and how. The copy is done between the provider and our Stripe; we don’t see the data in flight. This usually takes weeks.

​

Switching subscriptions

1. Check the subscription is still active on the current billing provider.
2. Confirm the renewal date is far enough out (24h safety window), so we don’t clash with the old billing provider renewal.
3. Confirm the card is valid on Polar (with a SetupIntent).
4. Cancel the subscription on the old billing provider.
5. Clear the migration_billing_paused flag (the status stays as-is).

• Source applies exclusive tax: import as exclusive, so Polar adds tax on top.
• Source is inclusive, or applies no tax: import as inclusive, keeping the customer’s current total. This means that the merchant absorbs the tax on their end.

​

The sources

​

Implementation notes

​

New module

​

Main classes

• MigrationJob one row per migration run for an org. The root: source platform and current step.
• MigrationRecord one row per imported thing (customer, product, subscription, order, …), mapping source_id → target_id with a status. It’s our idempotency layer, scoped per org, so we can trigger multiple migrations safely.
• SourceAdapter we will have one for every billing provider (e.g. StripeAdapter). Its main responsibility is to read the current billing provider API and provide a generic representation the migration service can work with. extract() must be incremental as customer data can be huge. It also stops billing on the source at cutover via stop_source_subscription(), the adapter’s only write.
• PanTransferStep the checklist for moving cards (step, owner, status, kind, inputs - see Appendix B). Stored as a JSONB column on MigrationJob: a list of step objects.
• MigrationService the main orchestrator.
• CanonicalRecord to have everything normalized in memory first (variants: CanonicalProduct / Customer / Subscription). The precheck engine reads these and returns a PrecheckReport (Appendix A); Appendix C shows the flow end to end.

​

Testing and rollout

• Start with PAN Copy in live, using my own Stripe account (pepy.tech) as the source and migrating a small, real subscription set.
• Then add one more friendly merchant as a second case.
• Keep everything behind a feature flag, enabled only for those orgs during the testing phase and removed once we’re confident.

​

Open questions

1. Where and how should we store the API keys of Stripe, LS, Paddle? Resolved: Use the secrets encryption pattern from secrets-encryption.mdx — wrap secrets in EncryptedString and map columns with EncryptedStringType.
2. Should we get notified when a migration is triggered?
3. How do we trigger the cutover on live? Resolved: a manual action via the checklist’s cutover step (merchant; Ops can too), gated on checklist completion.
4. What happens with subscriptions we can’t migrate? Resolved: the precheck flags them (past_due/unpaid/paused, uncopyable PMs); they stay on the old provider, staged as skipped, not imported.

​

Appendix A: Pre-checks

• Currency
  • Blocker: there must be only one account currency. Multiple currencies can’t be onboarded for now.
• Pricing
  • Blocker: only fixed prices are supported for now (tiered/dynamic pricing isn’t - we can still import the rest).
• Catalog
  • Blocker: duplicate product names (in case of manual creation).
• Customers
  • Warning: duplicate emails (in case of manual creation), we will reuse the existing ones.
  • Warning: if we reuse a Polar customer by email but PAN copy preserves the source cus_…, the copied card lands under a different customer. We should reconcile stripe_customer_id on reuse.
• Subscriptions
  • Warning: mention subscriptions that are on trial.
• Payments
  • Warning: flag subscriptions with wallet, Bacs, or legacy SEPA source payments we need to ask the customer to re-enter the details.
• Organization
  • Blocker: organization must be in a renewal-enabled status (REVIEW or ACTIVE).

​

Appendix B: The PAN transfer process

​

PAN copy (Stripe → Stripe)

• Stripe Customer Ids are kept between Stripe accounts.
• Payment Method Ids are not kept (new pm_… id, same underlying card).

​

PAN import (non-Stripe vault → Stripe)

1. Polar App: automatically.
2. Merchant: when filling information.
3. Polar Ops: manually from the backoffice.
4. Stripe / Billing Provider: by Polar Ops from the backoffice.

​

Appendix C: An implementation example

# 1. read + normalize from the source
#    Stripe: mint a short-lived access token from the stored OAuth refresh token
token = await stripe_oauth.refresh(job.source_refresh_token)  # rotates; persist token.refresh_token
records = [r async for r in StripeAdapter(api_key=token.access_token).extract()]
# records = [CanonicalProduct(...), CanonicalCustomer(...), CanonicalSubscription(...)]

# 2. precheck (no writes), then stage each record in the ledger
report = precheck.run(records, org)        # PrecheckReport(can_start=True, blockers=0, ...)
for r in records:
    repo.upsert(MigrationRecord(job_id=job.id, source_id=r.source_id, canonical=r))

# 3. import through the existing services (subscriptions created paused via the flag)
await product_service.import_from_canonical(canonical_product)
await subscription_service.import_from_canonical(canonical_subscription)

​

Appendix D: Stripe → Polar

​

Mapping

​

Reading the account

​

Stripe-specific prechecks

• Manual: source account is a Connect platform - only platform-account customers/PMs are copyable; anything on connected accounts is excluded.
• Blocker: India / RBI account - card data can’t cross the border, so the PAN copy can’t run (bidirectional).
• Blocker: tiered/graduated pricing (billing_scheme=tiered) can’t be represented.
• Blocker: metered pricing (usage_type=metered) - to be implemented later (Stripe now requires a Billing Meter; legacy usage records are gone).
• Blocker: subscription with multiple line items - can’t be represented.
• Blocker: collection_method=send_invoice - can’t be handled.
• Warning: multiple discounts on a subscription - Polar supports one; keep one and flag the rest.
• Warning: pause_collection - no Polar paused subscriptions, don’t import.
• Warning: past_due / unpaid - don’t import.
• Warning: in-flight refunds / open disputes on an invoice - don’t import, the money is still moving on Stripe.

​

Connecting the source (Stripe App OAuth)

• Authorize URL is channel-scoped: /oauth/v2/{chnlink_…}/authorize?client_id=ca_…&redirect_uri=…&state=…. Omitting the chnlink_ segment fails consent with “oauth client is not valid”.
• The token exchange authenticates as the account that owns the app (in prod, Polar’s platform account).
• The callback may arrive without state (Stripe-initiated installs); handle it (reconcile by account or require a Polar-initiated install).
• Refresh tokens rotate on every refresh; persist the new one each time.