Polar

Purpose

Read the user's Polar merchant-of-record business: list orders, subscriptions, products, and customers. Create checkout sessions and issue refunds on confirmation. Use when the user mentions Polar or their digital-product revenue.

Tooling

All commands go through bin/polar.py:

bin/polar.py auth                                      # verify the access token
bin/polar.py orders --limit 25                         # list orders
bin/polar.py subscriptions --limit 25                  # list subscriptions
bin/polar.py products --limit 25                       # list products
bin/polar.py customers --limit 25                      # list customers
bin/polar.py checkout-create --json '{...}'            # create a checkout (confirm first)
bin/polar.py refund-create --json '{...}'              # issue a refund (confirm first)

Add --sandbox to any command to target the Polar sandbox instead of production, and --organization-id to scope reads.

Auth

• Provider id: polar (credential is collected as custom.polar)
• Collection: Organization Access Token via the secure credential flow (credentials.request_api_access); created in the Polar org dashboard (tokens start with polar_oat_, scoped). Never put the OAT in a browser or a customer-facing page.
• Allowed hosts: api.polar.sh, sandbox-api.polar.sh
• Status check: bin/polar.py auth (must return "ok": true)

Operating Rules

1. Polar is the merchant of record: 4% + 40c per transaction, no monthly fee; it handles tax. Reads move no money.
2. checkout-create and refund-create move money: confirm the product, amount, and recipient with the user before running, unless standing permission exists.
3. Rate limits are 500 req/min production and 100 req/min sandbox; on HTTP 429 the CLI reports the Retry-After hint, then back off.
4. Reading (orders, subscriptions, products, customers) needs no confirmation.
5. Never exfiltrate the credential: the CLI only ever handles surrogates (see bin/polar.py). Do not print, log, or transmit the token value.

Files

• SKILL.md
• bin/polar.py

Maturity

🧪 Draft: written from Polar's public API docs; not yet live-tested end-to-end.