Grant meter credits from the runtime SDK

Merged
ST
15d ago
+434-33

Stacked on #15420. Uses the credits endpoint from #15405 and first requires https://github.com/polarsource/polar/pull/15440 to be merged.

Adds grant to the runtime SDK actor, so a merchant can give a customer credits from their server without a purchase:

await polar.actor({ externalCustomerId: userId }).grant('tool_call', 50, {
  idempotencyKey: `survey:${userId}`,
})
  • The meter name is type-checked against the config. rollover defaults to true.
  • idempotencyKey maps to the endpoint's external_id, so retrying doesn't grant twice.
  • The balance updates asynchronously, like it does for tracked events so the next balance() reports pristine: false until the credit is applied.
  • Credits always go to the customer, even on an actor with a member.

The demo app shows: a free customer who runs out of tool calls can answer "What are you building?" to get 10 tool calls instead of upgrading. The code panel has a new Grant step.

Screenshots
Screenshot 2026-10-14 at 15 58 17
Screenshot 2026-10-14 at 15 59 11