Zapmail
Overview
API Reference
Overview
API Reference
  1. Billing
  • Introduction
  • Quickstart
  • Authentication
  • MCP
  • Versioning
  • Errors
  • Webhooks
  • Rate Limits
  • Pagination
  • Changelog
  • Capabilities
    • Mailboxes
    • Pre-Warmed
    • Deliverability
    • Domains
    • Export to Sequencer
    • Zapbox
    • Team Management
    • ZapShield
    • ZapCare
    • AI Insight
    • Deliverability Tests
    • ZapSites
    • Zapwarm
    • ZapPulse
  • Billing
    • Understanding Zapmail billing
    • Wallet
  1. Billing

Wallet

The wallet is a prepaid USD balance that pays for mailboxes, plans, domains and other purchases. This page covers adding funds, reading the balance, auto recharge, invoices and add-on mailboxes. All paths are under https://api.zapmail.ai/api/v3.
Before you start: you need an API key in the x-auth-zapmail header and, for charges, billing details on the account (see Understanding Zapmail billing). Wallet responses are flat bodies, not the standard { status, message, data } envelope.

Top up the wallet#

1
Create a checkout link
Call Add Wallet Balance with the amount in USD. The response contains a Stripe Checkout URL in paymentLink. Nothing is added by this call.
2
Pay in the browser
Open paymentLink and pay by card. Automatic tax is enabled on the checkout, and the wallet is credited with the total the checkout collected, so the credited amount can be higher than amount.
3
Wait for the credit
The wallet is credited asynchronously after payment. Poll Get Wallet Balance until the balance changes. Once credited, eligible open invoices are paid from the new balance.
This charges your card, not your wallet. The card is charged when you complete the Stripe Checkout.
path optionally sets the page on the Zapmail web app that Stripe returns to (default /success). The call is throttled: while a wallet debit happened in the last minute, or more than two in the last 10 minutes, it returns 400. Retry later.

Check the balance#

The response has walletBalance (USD) and autoRechargeEnabled. autoRechargeDetails (amount and threshold) appears only while auto recharge is on. With x-workspace-key set, the balance returned is that of the workspace owner.

Auto recharge#

Enable or Disable Auto Recharge turns on automatic top-ups from a saved card. A check runs every 30 minutes. When the balance is below threshold, the card is charged minimumRechargeAmount.
With a card already saved, enable: true takes effect immediately and applies threshold and minimumRechargeAmount if you send them.
With no saved card, the response contains a Stripe Checkout paymentLink for adding one. Auto recharge is switched on after the card is saved, which happens asynchronously. When a card has to be added first, threshold defaults to 20 and minimumRechargeAmount to 50.
enable: false, or omitting enable, disables auto recharge. Always send enable explicitly.
Failures return 400 with the message Failed to enable auto-recharge.
This charges your card, not your wallet. The call itself charges nothing. After it is enabled, the saved card is charged minimumRechargeAmount each time the balance falls below threshold.
Auto recharge does not rescue every purchase
Add-on mailbox purchases return 400 on a short wallet even when auto recharge is on, and a base plan purchase with a short wallet and auto recharge on returns 200 with paymentProcessing: true without charging or buying anything. Keep the balance above the price before you purchase.

Invoices#

Get Subscription Invoice URL returns the hosted URL of the latest invoice of a mailbox subscription. Pass the Stripe subscriptionId from List Subscriptions.
This returns invoices for mailbox subscriptions only, not a list of wallet transactions. A subscription that does not exist, is not a mailbox subscription, or belongs to another account returns 403 with a body that contains only message.

Buy add-on mailboxes#

Buy Add-On Mailboxes adds mailbox slots on top of the account's base plan. quantity is a query parameter, not a body field.
1.
Confirm an active base plan exists. Add-ons need one, and the per-slot price follows that plan and its billing cycle.
2.
Check the wallet balance covers the full price (quantity times the per-slot price).
3.
Send the request. The paid invoice URL is returned in paymentLink.
4.
Poll List Subscriptions. The new slots appear once Stripe confirms the payment.
This charges your wallet. The full price is charged immediately to the wallet of the workspace owner. If the balance is lower, the call returns 400 Insufficient wallet balance. Required: $X, Available: $Y. and nothing is charged, even with auto recharge on. Not available on Pay as you go accounts.
Related: Understanding Zapmail billing, Purchase Mailbox Subscription, Add Billing Details.
Previous
Understanding Zapmail billing
Built with