Billing Troubleshooting Guide

Solutions for payment, subscription, and invoice-related issues with OpenClaw.

Payment Failed

Symptoms

• Subscription status shows "past_due"
• Email notification about failed payment
• Bots continue working but at risk of suspension
• Can't create new bots

Diagnostic Steps

Check Subscription Status

const billing = await fetch('/api/billing', {
  credentials: 'include'
}).then(r => r.json());
 
console.log('Status:', billing.subscription.status);
console.log('Period end:', billing.subscription.currentPeriodEnd);
console.log('Cancel scheduled:', billing.subscription.cancelAtPeriodEnd);

Review Polar.sh Dashboard

1. Log into polar.sh with subscription email
2. Navigate to Billing > Payment Methods
3. Check payment method status
4. Review failed payment attempts

Common Causes & Solutions

Cause: Card Expired

Solution:

1. Log into Polar.sh dashboard
2. Navigate to Billing > Payment Methods
3. Add new payment method
4. Set as default
5. Remove expired card
6. Payment retries automatically within 24 hours

Cause: Insufficient Funds

Solution:

1. Ensure sufficient balance in account
2. Payment automatically retried by Polar.sh
3. Or manually update payment method
4. Contact bank if card blocked

Cause: Card Declined by Bank

Solution:

1. Contact bank to authorize charge
2. Common reasons: fraud protection, international transaction block
3. Whitelist "Polar.sh" with bank
4. Try alternative payment method

Cause: Billing Address Mismatch

Solution:

1. Verify billing address matches card
2. Update address in Polar.sh dashboard
3. Retry payment manually

Manual Payment Retry

After fixing payment method:

// Subscription automatically retries payment
// Or create new checkout for same tier
 
const response = await fetch('/api/billing/checkout', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ tier: 'pro' }) // Your current tier
});
 
const { checkoutUrl } = await response.json();
window.location.href = checkoutUrl;

---

Can't Subscribe

Symptoms

• Checkout fails with error
• "Email verification required" message
• Payment processed but no subscription created
• Redirect loop on checkout page

Diagnostic Steps

1. Check Email Verification

// Verify email status
const user = await fetch('/api/user/profile', {
  credentials: 'include'
}).then(r => r.json());
 
if (!user.emailVerified) {
  console.error('Email verification required');
}

2. Check Browser Console

Open browser DevTools > Console:

• Look for CORS errors
• Check for failed API requests
• Verify no JavaScript errors

3. Test Different Payment Method

Try alternative payment:

• Different credit card
• Different browser
• Different device/network

Common Causes & Solutions

Cause: Email Not Verified

Error: "Email verification required before subscribing"

Solution:

1. Check inbox for verification email
2. Click verification link
3. Check spam folder if not found
4. Request new verification email in Portal settings
5. Retry subscription after verification

Cause: Polar.sh Account Issue

Solution:

1. Clear browser cache and cookies
2. Log out of Polar.sh and OpenClaw
3. Log back in to OpenClaw
4. Retry checkout
5. Contact support if persists

Cause: Payment Method Rejected

Solution:

1. Try different card
2. Use alternative payment (Apple Pay, Google Pay)
3. Contact card issuer to authorize
4. Try incognito/private browsing mode

Cause: Regional Restrictions

Some payment methods unavailable in certain regions.

Solution:

1. Check Polar.sh supported countries
2. Use international credit card
3. Contact support for alternative payment options

---

Subscription Not Active After Payment

Symptoms

• Payment successful (receipt received)
• Dashboard shows "no subscription"
• Can't create bots
• Bots show "subscription required" error

Diagnostic Steps

Check Subscription Status

const billing = await fetch('/api/billing', {
  credentials: 'include'
}).then(r => r.json());
 
if (!billing.hasSubscription) {
  console.log('No active subscription found');
  console.log('Check webhook processing or contact support');
}

Check Invoice History

const invoices = await fetch('/api/billing/invoices', {
  credentials: 'include'
}).then(r => r.json());
 
const recent = invoices.invoices[0];
console.log('Latest invoice:', recent);
console.log('Status:', recent.status);

Common Causes & Solutions

Cause: Webhook Processing Delay

Payment successful but webhook not yet processed.

Solution:

• Wait 5-10 minutes for webhook processing
• Refresh Portal dashboard
• Log out and back in
• Contact support if not resolved in 1 hour

Cause: Webhook Delivery Failed

Polar.sh couldn't deliver webhook to OpenClaw.

Solution:

1. Contact support with payment receipt
2. Include transaction ID from email
3. Support manually activates subscription
4. Usually resolved within 4 hours

Cause: Email Mismatch

Paid with different email than OpenClaw account.

Solution:

1. Verify email used for payment
2. Log into OpenClaw with matching email
3. Or contact support to link subscription
4. Provide both emails and transaction ID

---

Can't Upgrade or Downgrade

Symptoms

• Checkout fails when changing tier
• "Already subscribed" error
• Payment processed but tier unchanged
• Can't access upgrade options

Diagnostic Steps

Check Current Tier

const billing = await fetch('/api/billing', {
  credentials: 'include'
}).then(r => r.json());
 
console.log('Current tier:', billing.subscription.tier);
console.log('Can upgrade:', billing.subscription.status === 'active');

Solutions

To Upgrade

// Create checkout for higher tier
const response = await fetch('/api/billing/checkout', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ tier: 'ultra' }) // Target tier
});
 
const { checkoutUrl } = await response.json();
window.location.href = checkoutUrl;

To Downgrade

Process:

1. Cancel current subscription
2. Wait for current period to end
3. Subscribe to lower tier

// Step 1: Cancel current
await fetch('/api/billing/cancel', {
  method: 'POST',
  credentials: 'include'
});
 
// Step 2: After period ends, subscribe to new tier
// (Do this after currentPeriodEnd date)

---

Invoice Issues

Symptoms

• Can't download invoice PDF
• Invoice missing from list
• Wrong amount on invoice
• Tax calculation incorrect

Diagnostic Steps

List All Invoices

const response = await fetch('/api/billing/invoices', {
  credentials: 'include'
});
 
const { invoices } = await response.json();
 
invoices.forEach(inv => {
  console.log(`${inv.id}: $${inv.amount/100} - ${inv.status}`);
  console.log(`PDF: ${inv.pdfUrl}`);
});

Common Causes & Solutions

Cause: PDF Generation Pending

Recent invoice (under 1 hour old) PDF not ready.

Solution:

• Wait 1-2 hours for PDF generation
• Refresh invoice list
• Contact support if not available after 24 hours

Cause: Invoice Not Synced

Invoice exists in Polar.sh but not showing in OpenClaw.

Solution:

1. Log into Polar.sh dashboard directly
2. Download invoice from Polar.sh
3. Contact OpenClaw support to sync invoices
4. Provide transaction ID

Cause: Wrong Amount or Tax

Solution:

1. Verify billing address correct (affects tax)
2. Check for prorated charges (mid-cycle changes)
3. Review Polar.sh invoice for breakdown
4. Contact support with specific invoice ID if disputed

Cause: Missing Invoices

Solution:

1. Check date range filter in API call
2. Verify payment actually completed
3. Check spam folder for receipt emails
4. Contact support with payment confirmation

---

Cancellation Issues

Symptoms

• Cancellation request not processed
• Subscription still active after cancellation
• Charged after cancellation
• Can't reactivate cancelled subscription

Diagnostic Steps

Check Cancellation Status

const billing = await fetch('/api/billing', {
  credentials: 'include'
}).then(r => r.json());
 
console.log('Cancel at period end:', billing.subscription.cancelAtPeriodEnd);
console.log('Period ends:', billing.subscription.currentPeriodEnd);
console.log('Status:', billing.subscription.status);

Common Causes & Solutions

Cause: Cancellation Pending

Cancelled but period hasn't ended yet.

Solution:

• This is expected behavior
• Subscription active until period end
• Bots continue working until then
• No refund for remaining time

Cause: Charged After Cancellation

Solution:

1. Verify cancellation was before billing date
2. Check cancelAtPeriodEnd was true
3. Contact support with invoice if incorrectly charged
4. Include cancellation confirmation

Cause: Want to Reactivate

After cancelling, want to continue.

Solution:

1. If before period end: Contact support to undo cancellation
2. If after period end: Create new subscription via checkout
3. Bot data preserved for 30 days after expiration

---

Refund Requests

Symptoms

• Want refund for subscription
• Charged incorrectly
• Service not working as expected

Policy

• No refunds for partial month usage
• Pro-rated refunds for billing errors only
• Full refund if charged after cancellation
• 7-day money-back guarantee for new subscribers

Process

1. Email support@openclaw.ai with:

   • Invoice ID
   • Reason for refund
   • Account email
   • Transaction date

2. Wait 3-5 business days for review

3. Refund processed (if approved):

   • Via original payment method
   • Takes 5-10 business days to appear
   • Email confirmation sent

---

Tax and Compliance Issues

Symptoms

• Wrong VAT applied
• Need VAT exemption
• Tax certificate required
• Sales tax calculation incorrect

Solutions

VAT Exemption (EU Business)

1. Log into Polar.sh dashboard
2. Navigate to Billing > Tax Settings
3. Enter VAT ID
4. Polar.sh validates with VIES
5. Future invoices exclude VAT

Tax Certificate

1. Download invoice PDF (includes tax breakdown)
2. Request additional tax forms from support
3. Available documents:
   • Tax invoice
   • Payment confirmation
   • Service description

Wrong Tax Rate

Solution:

1. Verify billing address accurate
2. Update address in Polar.sh
3. Contact support to correct past invoices
4. Future charges use correct rate

---

Common Error Messages

Billing API Errors

Error	Cause	Solution
"Unauthorized"	Not logged in	Log into Portal
"Email verification required"	Email not verified	Check inbox, verify email
"Invalid tier"	Tier name typo	Use 'basic', 'pro', or 'ultra'
"No active subscription"	Subscription expired	Subscribe to plan
"Failed to create checkout"	Polar.sh unavailable	Wait and retry, or contact support
"Payment method required"	No card on file	Add payment method in Polar.sh

Payment Errors

Error	Cause	Solution
"Card declined"	Bank rejected	Contact bank, try different card
"Insufficient funds"	Not enough balance	Add funds, use different card
"Invalid card number"	Card number wrong	Verify card details
"Expired card"	Card past expiration	Use valid card
"Security code invalid"	CVV wrong	Check card CVV code

---

Emergency Billing Support

Critical Issues

Contact support immediately if:

• Charged multiple times for same period
• Can't access account after payment
• Subscription cancelled without authorization
• Security concern with payment data

Emergency Contact:

• Email: billing@openclaw.ai
• Subject: "URGENT BILLING ISSUE"
• Include: Invoice ID, transaction ID, account email

Response Times:

• Critical billing issues: under 4 hours
• Standard billing support: 24 hours
• Invoice/receipt requests: 48 hours

---

Prevention Best Practices

Payment Management

• Keep payment method current
• Set calendar reminder before card expiration
• Add backup payment method
• Enable billing email notifications

Monitoring

• Review monthly invoices
• Check subscription status monthly
• Monitor quota to avoid unexpected upgrades
• Keep billing address updated

Documentation

• Save invoice PDFs for accounting
• Keep payment confirmations
• Document any billing disputes
• Track subscription changes

---

FAQ

Q: When am I charged? A: Monthly on subscription start date (e.g., subscribed Jan 15 = charged 15th each month).

Q: Can I get refund for unused time? A: No, subscriptions billed monthly with no partial refunds.

Q: What happens if payment fails? A: 3-day grace period, then subscription suspended and bots stopped.

Q: Can I change billing date? A: No, billing date fixed to subscription start date.

Q: Do you offer annual billing? A: Not currently. Contact support for enterprise annual contracts.

Q: What payment methods accepted? A: All major credit cards via Polar.sh. Additional methods vary by region.

Q: Is billing information secure? A: Yes, Polar.sh handles all payment processing (PCI compliant).

Q: Can I get invoice emailed automatically? A: Yes, Polar.sh emails invoice on successful payment.

---

Next Steps

• Bot Troubleshooting
• Billing Management Guide
• Contact Billing Support