Billing & Payments

Manage subscriptions, purchase credits, and handle payments via the Stripe-powered billing API.

PushMail uses Stripe for all billing operations. You can subscribe to a plan, purchase one-time credits, and manage payment methods through the API or dashboard.

Plans

Plan	Price	Included Emails	Overage Rate
Free	$0/mo	0 (pay per email)	$0.003/email
Starter	$19/mo	10,000	$0.0025/email
Growth	$49/mo	50,000	$0.0015/email
Scale	$149/mo	250,000	$0.0008/email

All plans support credit card and ACH (US bank account) payments.

Create a Stripe Checkout session to subscribe to a paid plan.

POST

/billing/checkout

Create a subscription checkout session

Request

{
  "planId": "growth",
  "successUrl": "https://yourapp.com/billing?success=true",
  "cancelUrl": "https://yourapp.com/billing?canceled=true"
}

Parameter	Type	Description
`planId`required	string
`successUrl`	string
`cancelUrl`	string

Response

{
  "data": {
    "checkoutUrl": "https://checkout.stripe.com/c/pay/...",
    "sessionId": "cs_live_..."
  }
}

Redirect the user to checkoutUrl to complete payment.

Purchase Credits

Buy one-time credit packages to top up your balance.

POST

/billing/credits

Create a credit purchase checkout session

Request

{
  "packageId": "credits_50"
}

Parameter	Type	Description
`packageId`required	string
`successUrl`	string
`cancelUrl`	string

Available Credit Packages

Package	Price	Credits	Bonus
credits_10	$10.00	$10.00	--
credits_25	$25.00	$25.00	--
credits_50	$50.00	$50.00	--
credits_100	$100.00	$105.00	+$5.00
credits_500	$500.00	$550.00	+$50.00

GET

/billing/credits

List available credit packages

Get Subscription Status

GET

/billing/subscription

Get current plan, subscription details, and recent invoices

Response

{
  "data": {
    "plan": {
      "id": "growth",
      "name": "Growth",
      "monthlyPriceCents": 4900,
      "includedEmails": 50000,
      "features": ["..."]
    },
    "planStatus": "active",
    "creditBalanceCents": 2500,
    "subscription": {
      "id": "sub_...",
      "status": "active",
      "currentPeriodStart": 1709251200,
      "currentPeriodEnd": 1711929600,
      "cancelAtPeriodEnd": false
    },
    "invoices": [...],
    "recentPayments": [...],
    "availablePlans": [...]
  }
}

Get Usage & Credit Balance

Retrieve your current month's email usage, cost, credit balance, and historical usage data.

GET

/billing/usage

Get current month usage and credit balance

Response

{
  "data": {
    "creditBalance": 2500,
    "plan": "growth",
    "currentMonth": {
      "month": "2026-03",
      "emailsSent": 12500,
      "totalCostCents": 3750,
      "currentRateCents": 0.2
    },
    "history": [
      {
        "month": "2026-02",
        "emailsSent": 8000,
        "totalCostCents": 2400
      }
    ]
  }
}

Manage Billing (Customer Portal)

Open the Stripe Customer Portal to update payment methods, view invoices, or cancel subscriptions.

POST

/billing/portal

Create a Stripe Customer Portal session

Response

{
  "data": {
    "portalUrl": "https://billing.stripe.com/p/session/..."
  }
}

Redirect the user to portalUrl.

Webhooks

PushMail automatically processes Stripe webhook events at POST /api/v1/billing/webhooks. The following events are handled:

Event	Action
`checkout.session.completed`	Activates subscription or adds credits
`payment_intent.succeeded`	Records successful payment
`customer.subscription.updated`	Updates plan and status
`customer.subscription.deleted`	Reverts to free plan
`invoice.payment_failed`	Marks plan as past_due

Configure your Stripe webhook endpoint to point to https://your-domain.com/api/v1/billing/webhooks and set the STRIPE_WEBHOOK_SECRET environment variable.

Environment Variables

Set these secrets via wrangler secret put:

STRIPE_SECRET_KEY -- Your Stripe secret key (starts with sk_live_ or sk_test_)
STRIPE_WEBHOOK_SECRET -- Stripe webhook signing secret (starts with whsec_)

On this page