Credits

Credits are Commune’s unit for phone and SMS operations. Every SMS sent, MMS, inbound message received, and phone number rented deducts credits from your balance.

How credits work

Every organization has two credit pools:

Included credits — replenish monthly based on your plan. They reset on your billing cycle and do not roll over.
Purchased credits — from one-time bundle purchases. They roll over month-to-month and never expire.

When an operation runs, included credits are consumed first. Purchased credits are drawn from only after included credits are exhausted.

Credits by plan

Plan	Included credits/month
Free	200
Agent Pro	500
Business	5,000
Enterprise	Unlimited

Credit costs

Operation	Credits
US/CA outbound SMS (per segment)	2
US/CA outbound MMS	5
US/CA inbound SMS	1
Phone number rental	150/month (prorated)
International SMS	varies — see SMS

SMS messages over 160 characters are split into segments. Each segment costs the per-segment rate. Standard GSM-7 encoding allows 160 chars/segment; Unicode (emoji, non-Latin) allows 70 chars/segment.

Check your balance

import { CommuneClient } from 'commune-ai';

const commune = new CommuneClient({ apiKey: process.env.COMMUNE_API_KEY });

const balance = await commune.credits.get();

console.log(`Available: ${balance.total} credits`);
console.log(`Included: ${balance.included}`);
console.log(`Purchased: ${balance.purchased}`);
console.log(`Used this cycle: ${balance.usedThisCycle}`);
console.log(`Resets at: ${balance.cycleResetAt}`);

from commune import CommuneClient

client = CommuneClient()

balance = client.credits.get()

print(f"Available: {balance.total} credits")
print(f"Included: {balance.included}")
print(f"Purchased: {balance.purchased}")
print(f"Used this cycle: {balance.used_this_cycle}")
print(f"Resets at: {balance.cycle_reset_at}")

get_credit_balance()

curl https://api.commune.email/v1/credits \
  -H "Authorization: Bearer comm_..."

Purchase credits

Credits can be topped up at any time via a credit bundle. Bundles are one-time purchases — they do not create a recurring subscription.

Available bundles

Bundle	Credits	Price	Per credit
Starter	1,000	$12	$0.0120
Growth	5,000	$55	$0.0110
Scale	20,000	$200	$0.0100

Larger bundles have a lower per-credit rate. All purchased credits roll over indefinitely.

Initiate a purchase

The purchase flow creates a Stripe Checkout session. Redirect your user to the returned URL to complete payment.

import { CommuneClient } from 'commune-ai';

const commune = new CommuneClient({ apiKey: process.env.COMMUNE_API_KEY });

const checkout = await commune.credits.purchase({
  bundleId: 'growth',
  success_url: 'https://your-app.com/billing?credits=success',
  cancel_url: 'https://your-app.com/billing',
});

// Redirect your user to complete the purchase
console.log(checkout.checkout_url);

from commune import CommuneClient

client = CommuneClient()

checkout = client.credits.purchase(
    bundle_id="growth",
    success_url="https://your-app.com/billing?credits=success",
    cancel_url="https://your-app.com/billing",
)

print(checkout.checkout_url)

purchase_credits(bundle_id="growth")

curl -X POST https://api.commune.email/v1/credits/checkout \
  -H "Authorization: Bearer comm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "bundle": "growth",
    "success_url": "https://your-app.com/billing?credits=success",
    "cancel_url": "https://your-app.com/billing"
  }'

Credits are added automatically via Stripe webhook after payment is confirmed. There is typically a 1–3 second delay between payment completion and credits appearing in your balance.

What happens when credits run out

If an operation is attempted with insufficient credits, it fails with a 402 response:

{
  "error": "insufficient_phone_credits",
  "balance": 12,
  "required": 150
}

The balance and required fields tell you exactly how short your account is, so you can surface a clear top-up prompt to your users.

API reference

Get Balance

Query your current credit balance, cycle usage, and reset timestamp.

List Bundles

Retrieve available credit bundles and per-credit pricing.

Purchase Credits

Create a Stripe Checkout session to top up your balance.

Get Started

SDKs

Email

Commune OAuth

Phone & SMS

Security

Integrations

Examples

Community

How credits work

Credits by plan

Credit costs

Check your balance

Purchase credits

Available bundles

Initiate a purchase

What happens when credits run out

API reference

Get Balance

List Bundles

Purchase Credits

​How credits work

​Credits by plan

​Credit costs

​Check your balance

​Purchase credits

​Available bundles

​Initiate a purchase

​What happens when credits run out

​API reference

Get Balance

List Bundles

Purchase Credits

How credits work

Credits by plan

Credit costs

Check your balance

Purchase credits

Available bundles

Initiate a purchase

What happens when credits run out

API reference