Billing and Reviews

CodePeel uses a review-based billing model. Every PR review, IDE review, MCP tool call, and chat interaction consumes reviews from your monthly quota. Plans are managed through Polar, our payment provider.

---

Plans

*Max tier has an abuse protection cap of 5,000 reviews/month (far beyond normal usage).

All plans include: inline PR comments, walkthrough summaries, health score, secret scanning, SAST analysis, architecture review, sequence diagrams, incremental reviews, VS Code extension, MCP server, chat commands, pre-merge checks.

---

How Review Deductions Work

Reviews are consumed when a PR is analyzed. The cost depends on the total diff size (additions + deletions across all files):

This tiered model ensures small, focused PRs are inexpensive while large PRs requiring more analysis are priced proportionally.

What Counts as a Review

All review sources draw from the same monthly pool.

Model Credit Costs

CodePeel currently uses free-tier AI providers for all models. Every supported model costs 0 credits per review — switching models does not change cost. Premium model tiers may be introduced later for Max subscribers.

Failed Review Refunds

GitHub PR reviews: If a review fails due to AI error, timeout, or service unavailability, the deduction is automatically refunded.

IDE / MCP reviews: These routes do not refund on failure. If your IDE review errors mid-stream, the review is still counted against your quota. These endpoints have shorter timeouts and no automatic retry.

---

How It Works

Subscription Lifecycle

1. Select a plan from the billing page
2. Redirected to Polar checkout
3. Polar processes payment
4. CodePeel updates your account: tier, quota, subscription status
5. Usage counter resets to 0 on upgrade
6. On the 1st of each month, usage counters reset

Quota Enforcement

When a review is triggered:

1. System checks your tier and reviews used against your monthly quota
2. If reviews remain, the review proceeds
3. If quota exhausted, the review is blocked with a comment on the PR
4. Max tier checks against the 5,000 abuse-protection cap

Per-minute Rate Limiting

Reviews are limited to 20 per minute. When the limit is reached, subsequent reviews are queued until a slot opens.

• All tiers: 20 requests/minute for review/fixes/summarize, 15/minute for chat

Rate limits degrade gracefully — if a rate-limit check fails, the review proceeds rather than blocking.

Monthly Quota Reset

Usage counters reset on the 1st of each month. Max-tier users are skipped (unlimited, but capped at the 5,000 abuse-protection limit).

---

Checking Your Usage

Navigate to Billing in the dashboard sidebar. Two primary cards:

Current Plan — active tier, monthly price, next payment date. Warning if scheduled for cancellation.

Usage Summary — reviews consumed / total quota with progress bar:

• Blue: under 70% usage
• Yellow: 70–89% usage
• Red: 90%+ or quota exhausted

Max tier shows total reviews consumed without a cap indicator.

Programmatic Access

MCP:

check_credits

API:

GET /api/ide/credits/balance
Authorization: Bearer <token>

Response:

{
  "tier": "pro",
  "monthlyQuota": 500,
  "reviewsUsedThisPeriod": 127,
  "reviewsRemainingThisPeriod": 373,
  "usageResetAt": "2026-06-01T00:00:00.000Z"
}

---

Upgrading Your Plan

1. Go to Billing in sidebar
2. Click Upgrade (to Pro or Max)
3. Complete payment on Polar checkout
4. Redirected back with new plan active immediately
5. Usage counter resets to 0 on upgrade

Supported subscriptions: pro_subscription, pro_yearly_subscription, max_subscription, max_yearly_subscription.

---

Switching Plans

1. Cancel current plan from billing page
2. Current plan stays active until period ends
3. Subscribe to new plan

Usage counter resets on switch. No access loss during transition.

When you switch between plans, your tier, quota, and billing interval update automatically.

---

Cancelling Your Plan

1. Go to Billing → Manage Plan → Cancel Plan
2. Confirm cancellation

After cancellation:

• Plan stays active until period end
• "Cancels at period end" indicator shown
• After period ends: account downgrades to Free
• All review history, settings, learnings, configuration preserved
• Quota reverts to 30 reviews/month

Uncancelling: Resubscribe before the period ends. Active status is restored automatically.

---

Payment Provider

CodePeel uses Polar for checkout, subscriptions, invoicing, payment methods, and refunds.

Customer Portal

Paid subscribers can access Polar portal to:

• Update payment method
• View/download invoices
• See payment history
• Manage subscription directly

Click Manage in Payment Method section or Polar Portal in plan management panel.

Supported Payment Methods

Credit/debit cards via Polar. CodePeel stores no payment card information.

Invoices & Receipts

Available through Polar customer portal. Downloadable as PDF for expense reporting.

---

Billing History

Billing page shows transaction history from CodePeel records and Polar API.

Status badges: Active (current), Paid (previous cycle), Canceled, Refunded, Partial Refund, Failed (declined), Pending.

Paginated, refreshable via Refresh button (triggers Polar sync).

---

When Reviews Run Out

GitHub PR Reviews

• Review not processed
• Comment posted: "CodePeel is paused — monthly quota exceeded"
• Link to upgrade
• Resumes automatically on 1st of next month

IDE / MCP Reviews

• 402 HTTP response with a quota error code
  • /api/ide/review returns CREDITS_EXHAUSTED (free/pro/max caps)
  • /api/ide/chat and /api/fixes return REVIEWS_EXHAUSTED
• Includes tier, reviews used, quota
• Free: "No reviews remaining. Upgrade to Pro for 500 reviews/month."
• Pro: "No reviews remaining this period. Reviews reset at start of next billing cycle."
• Max: "Monthly review cap reached (5000). Contact support if you need more."

Payment Failures

If payment declined, subscription enters past_due:

• Warning banner on billing page
• Reviews blocked: "Payment failed. Update payment method at codepeel.com/app/billing"
• Update card → charge succeeds → reviews resume

---

Private Repositories

All repositories (public and private) are available on all tiers. There is no repository limit or private repo restriction on any plan.

---

Team Billing

Shared installations use author-based billing. Each developer billed for PRs they author:

See Teams documentation for setup details.

---

Subscription Sync

Billing page includes manual sync to reconcile with Polar:

• Just subscribed but plan not active
• Wrong tier after plan change

Click Refresh to trigger sync. Does not reset usage counters (prevents abuse).

---

Troubleshooting

"No reviews remaining" but I just subscribed

1. Click Refresh on billing page
2. Wait 10 seconds, reload
3. Background sync corrects within minutes

Payment failed banner won't go away

1. Click Update Card on banner or Manage in Payment Method
2. Update payment method in Polar portal
3. Retry charge succeeds → banner clears

Reviews not resetting on the 1st

• Check the usageResetAt date in the API response
• Max tier is skipped by the reset (unlimited, capped at 5,000)
• If the reset did not run, contact support for a manual reset

Checkout redirects but plan not active

• Wait 2–3 minutes for background sync
• Click Refresh
• Contact support with user ID if stuck

Rate limited but quota shows reviews remaining Rate limits and monthly quotas are independent. You can have monthly quota remaining but be rate-limited in the moment. Wait for indicated time — review proceeds automatically.

---

FAQ

Do unused reviews roll over? No. Quota resets to 0 on the 1st of each month. No rollover.

Does VS Code extension use separate quota? No. All sources (GitHub PRs, VS Code, MCP, chat) draw from same monthly pool.

What happens if I downgrade to Free? All history, settings, learnings, configuration preserved. Quota reverts to 30/month. Lose Pro/Max features (auto-fix, auto-test, custom rules).

Can I get a refund? Refunds handled through Polar. Appears in billing history as "Refunded" or "Partial Refund". Contact support if charged incorrectly.

How is annual plan billed? Full year upfront ($99.99 Pro, $249.99 Max). Monthly quota still resets every month (500/month Pro, unlimited Max). Annual price = 16.6% discount vs monthly.

Who gets charged on shared repos? PR author's CodePeel account. External contributors → owner fallback. See Team Billing.

---

Feature Comparison by Plan

Custom rules in .codepeel.yml are silently skipped on Free tier. Upgrade to enable.

---

API Reference

Check Balance

GET /api/ide/credits/balance
Authorization: Bearer <token>

Returns tier, quota, usage, subscription status. Triggers background sync if inconsistent with Polar.

Sync Subscription

POST /api/billing/sync
Authorization: Bearer <token>

Reconciles account with Polar. Updates tier, status, period end. Does not reset usage.

Get Billing History

GET /api/billing/transactions?page=1&limit=20
Authorization: Bearer <token>

Paginated history from Polar.

Cancel Subscription

POST /api/billing/cancel
Authorization: Bearer <token>

Schedules cancellation at the end of the current billing period. Access retained until then.

Open Customer Portal

POST /api/billing/portal
Authorization: Bearer <token>

Returns Polar portal session URL.

Create Checkout Session

POST /api/checkout/polar
Authorization: Bearer <token>
Content-Type: application/json

{ "type": "pro_subscription" }

Types: pro_subscription, pro_yearly_subscription, max_subscription, max_yearly_subscription.

---

Related Documentation

• Configuration — .codepeel.yml settings including custom rules (Pro/Max only)
• MCP Server — Programmatic access to reviews, fixes, and chat
• Pre-merge Checks — Quality gates that block merges