Zapmail billing has four parts: billing details used on invoices, a prepaid wallet, subscriptions (recurring plans), and one-off or recurring product purchases that draw on the wallet. This page explains how they fit together and what happens when a purchase costs more than the wallet holds.Every purchase endpoint charges for real. There is no sandbox, and requests carry no idempotency key, so a repeated request can charge twice. Check the wallet balance and the request before you send it.
Billing details#
Billing details (company, contact name, address and phone) are stored per workspace. Add Billing Details and Update Billing Details both save the same record: if the workspace has one it is overwritten, otherwise one is created. Add them before any purchase that needs an address, such as buying a domain.Both endpoints require addressLineTwo and addressLineThree to be present in the body. Send null when there is no value. When the details are for your primary workspace, the account holder's name is updated as well.The wallet#
The wallet is a USD balance that belongs to the account owner. Most purchases are paid from it first. You fund it in two ways:A manual top-up through a Stripe Checkout link (Add Wallet Balance). You pay by card, and the wallet is credited after the payment completes. Who pays: the wallet charged is that of the account owner of the workspace the request runs in. With x-workspace-key set, that is the owner of that workspace, not necessarily the key owner.Subscriptions and plans#
Mailbox capacity is sold as a base plan. Other products have their own subscriptions. List Subscriptions returns all of them for the account: mailbox plans and add-ons, Pre-Warmed, ZapShield, Deliverability Tests and AI Insight, and, when you do not filter by type, Zap Care, Zapwarm and health check subscriptions.Add-on mailboxes#
Buy Add-On Mailboxes adds mailbox slots to an active base plan. The price per slot follows the base plan and its billing cycle. quantity is a query parameter.Cancel a plan#
Cancel Subscription cancels a mailbox subscription at the end of the current period, or reverts a scheduled cancellation. A PAST_DUE subscription is cancelled immediately. Mailboxes on a cancelled subscription are scheduled for removal.Invoices#
Get Subscription Invoice URL returns the hosted invoice URL for the latest invoice of a mailbox subscription. It does not list wallet transactions.How purchases are charged#
| Purchase | Charging behaviour |
|---|
| Add-on mailboxes | Full price from the wallet, immediately. |
| Pre-Warmed plan | Full price from the wallet, immediately; renews monthly. |
| Domains, aged domains, quick setup | Wallet balance applied first; the remainder is billed on an invoice that you pay by link. |
| ZapShield, Zap Care, Deliverability Tests, AI Insight | An invoice is settled from wallet credit; any uncovered amount stays due on the hosted invoice. |
Each endpoint page states exactly how it charges under a Charges your wallet. line.When the wallet is short#
The outcome depends on the endpoint. Do not assume one behaviour.Add-on mailboxes: the call returns 400 and nothing is charged, even when auto recharge is enabled. Top up first, then retry.
Domains and invoice-based products: the wallet is applied first and the remainder stays due on a hosted invoice. The response carries the link (invoiceLink, redirect or checkoutUrl, depending on the endpoint). Nothing completes until that invoice is paid.
ZapShield monthly and annual: the saved card is charged for the shortfall if auto recharge is on; otherwise the request fails with 400.
A manual top-up can be refused (400) when the account has had recent wallet debits: the call is throttled while a debit happened in the last minute or more than two in the last 10 minutes. Retry after a short wait.Response shapes#
Wallet and purchase endpoints return flat bodies such as { "message": ..., "paymentLink": ... } rather than the standard { status, message, data } envelope, and some of their failures return only a message. The endpoint pages describe each one.