Fondoo
GitHubStart your 7-day trial for $0Start trial
Docs

Connect Polar to Fondoo

Live4 min readUpdated

If you sell with Polar, this connection lets Fondoo see your paid orders, refunds and subscriptions. Your AI agent can then report revenue, credit sales to the visits that led to them, and keep customers' plans in your app up to date. Fondoo only reads. It cannot refund, cancel or change anything in Polar.

What Fondoo can do with it

Six read-only actions, used through connector_action:

  • transactions.pull: paid orders and succeeded refunds.
  • subscriptions.pull: subscription status (active, past due, cancelled or revoked).
  • customers.list: customer IDs and emails.
  • webhooks.verify and webhooks.parse: check and read Polar webhook deliveries.
  • dashboard.link: a link into your Polar dashboard for a person to open.

After you bind the connection to a site with connect_revenue_source, Fondoo imports sales as orders and analytics conversions. Subscriptions become entitlements that can switch a customer's plan in your app. Webhooks and sync_revenue_source keep it current.

What needs your approval: an agent binding a live source or changing its product map needs the owner's approval. Reads never do. Refunds and cancellations stay in Polar.

Before you start

  • A Polar organization. API access is free. Polar's sales fees are on its fees page. They changed for new organizations in 2026, so check the page rather than older blog posts.
  • Production or sandbox. The sandbox at sandbox.polar.sh needs its own login and organization. Production tokens don't work there, and sandbox tokens don't work in production (sandbox).
  • Live mode in Fondoo needs a paid Fondoo plan. Test mode works on any plan.

Step by step: get your credentials

  1. Sign in to Polar (or the sandbox) and open your organization.
  2. Go to Settings and find the Developers section (organization access tokens).
  3. Click New Token.
  4. Give it a name such as Fondoo and pick an expiration. Polar's docs don't list the choices. A shorter expiry is safer, but you will need to rotate it.
  5. Tick only these scopes:
    • orders:read: sales.
    • refunds:read: refunds.
    • subscriptions:read: subscription status.
    • customers:read: customer IDs and emails.
  6. Create the token and copy it. It starts with polar_oat_.
  7. Optional: note your organization slug (the short name in your dashboard URL). Fondoo uses it only to build dashboard links.

What goes where:

Fondoo fieldWhat to paste
Organization access token (accessToken)the polar_oat_... token
Environment (environment)sandbox for a sandbox token. Leave empty for production
Organization slug (organizationSlug)optional, for dashboard links only
Webhook secret (webhookSecret)leave empty for now. Add it in the Webhooks step

Connect it in Fondoo

In the dashboard

  1. Open Connections.
  2. Under Available, find Polar (in Payments) and click Use a key.
  3. Click Open secure key entry (single use, expires after 15 minutes). Paste the token and any optional fields, then save.
  4. Click Check connection on the new card.

By asking your agent

Example prompt:

Connect my Polar organization to my site and import my sales. Send me a secure link for the token.

The agent runs:

add_connection_key({ provider: "polar", siteId: "<site id>" })
test_connection({ connectionId: "<id>" })
connect_revenue_source({ siteId: "<site id>", connectionId: "<id>", mode: "live",
  productMap: { "<Polar product ID>": "pro" } })   // returns webhookUrl
sync_revenue_source({ sourceId: "<source id>" })

Unmapped products still count as revenue. They just don't grant a plan. For a help link only: connect_service({provider:"polar", siteId}) (signed, valid 15 minutes).

Over REST: POST https://api.getfondoo.com/v1/ops/<operation> with Authorization: Bearer <your Fondoo API key> and the same JSON, for example POST /v1/ops/add_connection_key with {"provider":"polar","siteId":"<site id>"}.

Webhooks

  1. Copy the webhookUrl from connect_revenue_source (or get_revenue_sources). It looks like https://<Fondoo API host>/webhooks/revenue/<connectionId>.
  2. In Polar, open your organization settings, go to webhooks and click Add Endpoint (endpoints).
  3. Paste the URL and leave the format on Raw.
  4. Select these events: order.paid, order.refunded, refund.created, refund.updated, and the subscription events (subscription.created, subscription.updated, subscription.active, subscription.canceled, subscription.uncanceled, subscription.revoked).
  5. Save and copy the secret. It starts with whsec_.
  6. In Fondoo run rotate_connection_key({connectionId}). On the secure page, paste the token again, plus the secret in Webhook secret. The page replaces all fields together.

Polar signs deliveries with the Standard Webhooks headers webhook-id, webhook-timestamp and webhook-signature (delivery). Polar changed its secret format on 8 September 2026. Fondoo accepts both the new Standard Webhooks secrets and older Polar secrets. Fondoo refuses deliveries more than 5 minutes old. Polar disables an endpoint after 10 failures in a row, so fix errors quickly.

Fondoo checkouts set metadata.visit_id and metadata.external_user_id and pass external_customer_id, so sales can be credited to the right visit and user.

Test that it works

  1. Run test_connection. It confirms orders:read. The other scopes show as "unknown" until first used. That's normal.
  2. Run sync_revenue_source({sourceId}). Then check get_revenue_sources({siteId}) for lastSyncAt and no lastError.
  3. In the sandbox, buy a product. In Polar, the webhook endpoint's delivery list should show a success.

Troubleshooting

  • 401 Unauthorized. The token is wrong, expired or from the other environment. Sandbox tokens need Environment set to sandbox.
  • 403 on subscriptions, refunds or customers. The token is missing that scope. Create a new token with all four scopes and rotate it in.
  • Webhook endpoint disabled. Polar turns it off after 10 failed deliveries in a row. Fix the secret or URL, then re-enable it in Polar. Run sync_revenue_source to catch up.
  • Signature check fails. Make sure you pasted the full whsec_... secret for this endpoint and that the format is Raw.
  • "This site and mode already has a source for this provider". One Polar source per site and mode. Find it with get_revenue_sources.
  • 429 Too Many Requests. Polar allows 500 requests per minute in production and 100 in sandbox per organization (API introduction). Fondoo budgets 60 per minute.

Limits, data and security

  • What Fondoo stores: the token and webhook secret, encrypted, never shown again. From Polar it keeps order and refund amounts, subscription status, and customer IDs and emails.
  • Rotate: create a new token in Polar, then rotate_connection_key({connectionId}), and revoke the old token.
  • Disconnect: disconnect_revenue_source({sourceId}) stops the feed (imported data stays). delete_connection({connectionId}) deletes the stored token. Then revoke the token and remove the webhook endpoint in Polar.
  • Fondoo uses Polar API version 2026-10. Dashboard links use observed routes that Polar does not document, so they may open a general page.