[strandhvilliam]

Stacked on #15420. Uses the credits endpoint from #15405 and first requires #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

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
orbit	Ready	Preview	Oct 15, 2026 10:36am UTC
polar-test	Ready	Preview	Oct 15, 2026 10:36am UTC

[cubic-dev-ai]

All reported issues were addressed across 15 files

<sub>This PR changes payment, billing, or quota logic. Ultrareviews find 2.4x more serious bugs than standard reviews. Comment @cubic-dev-ai ultrareview to run one.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Requires human review: Adds a runtime SDK grant API and demo survey flow that grants meter credits without a purchase. This is a new public billing capability with financial/product tradeoffs (default rollover, idempotency, member-actor semantics) that need human sign-off.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[cubic-dev-ai]

1 issue found across 5 reviewed files. 19 files intentionally excluded from review.

Confidence score: 3/5

• The global meter lookup in customer-meters.ts can reject a valid meter when another accessible organization has the same ID, even though customer_id identifies the intended organization. Resolve the meter within that organization.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="clients/packages/polar/src/internal/api/customer-meters.ts">

<violation number="1" location="clients/packages/polar/src/internal/api/customer-meters.ts:24">
P2: This global lookup rejects duplicate meter IDs across accessible organizations even though `customer_id` identifies the customer's organization. Resolve the meter within that organization, as the external-ID credit endpoint does.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[cubic-dev-ai]

P2: This global lookup rejects duplicate meter IDs across accessible organizations even though customer_id identifies the customer's organization. Resolve the meter within that organization, as the external-ID credit endpoint does.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At clients/packages/polar/src/internal/api/customer-meters.ts, line 24:

<comment>This global lookup rejects duplicate meter IDs across accessible organizations even though `customer_id` identifies the customer's organization. Resolve the meter within that organization, as the external-ID credit endpoint does.</comment>

<file context>
@@ -13,13 +14,26 @@ export const creditCustomerMeter = async (
+  }
+  // Polar IDs and external IDs can't be mixed in one credit request
+  if ('customer_id' in identifier) {
+    const meter = await getDeployedMeter(sdk, externalMeterId)
+    return sdk.customerMeters.credits({
+      ...identifier,
</file context>

[cubic-dev-ai]

All reported issues were addressed across 4 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[cubic-dev-ai]

1 existing issue remains and no new issues found across 5 files (changes from recent commits).

Confidence score: 3/5

• getDeployedMeterId in clients/packages/polar/src/client/actor.ts can reject an external-customer grant when the meter ID exists in multiple accessible organizations, even though the credits endpoint resolves external_meter_id. Align the meter lookup with that resolution so valid grants aren’t rejected.

<sub>Requires human review: Auto-approval blocked by 4 unresolved issues from previous reviews.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Requires human review: Auto-approval blocked by 2 unresolved issues from previous reviews.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Requires human review: Auto-approval blocked by 2 unresolved issues from previous reviews.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
Polar	🟢 Ready	View Preview	Oct 15, 2026, 9:22 AM

💡 Tip: Enable Automations to automatically generate PRs for you.

[cubic-dev-ai]

No issues found across 13 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Requires human review: Adds a new public grant SDK operation and a demo flow that repeatedly grants credits without idempotency; the main human judgment is approving this new credit-granting API and the demo's unlimited-repeat behavior.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 2 files (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Requires human review: Auto-approval blocked by 1 unresolved issue from previous reviews.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[pieterbeulque]

Nice!