> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pilotstatus.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Reselling: how billing works and what your system must track

> For anyone reselling WhatsApp connections and phone lines: when Pilot Status charges each number and each line, what happens when a payment fails, and what your system must record to bill your own customers without paying for the ones who already left.

If you resell WhatsApp connections or phone lines to your own customers, Pilot Status bills **you**, and you bill your customers. This page explains when each charge happens on our side and what your system must record so both ends match: bill your customer before we bill you, and stop paying for customers who have left.

The full detail of each rule is in [Extra numbers & On Demand](https://docs.pilotstatus.com.br/api/extra-numbers.md), [Phone line pricing and billing](https://docs.pilotstatus.com.br/phone-lines-pricing.md) and [Plans](https://docs.pilotstatus.com.br/plans.md). To automate it, see [Key types](https://docs.pilotstatus.com.br/api/key-types.md), [Create workspaces](https://docs.pilotstatus.com.br/api/workspaces.md), [Wallet and card via API](https://docs.pilotstatus.com.br/api/wallet-and-card.md) and [Workspace webhooks](https://docs.pilotstatus.com.br/api/workspace-webhooks.md).

## One workspace per end customer

**Keep each of your customers in a workspace of their own.** Billing, suspension and the wallet all work per workspace. If every customer shares your workspace, one failed renewal stops all of them at once; with one workspace per customer, a failed renewal suspends **only that customer's numbers**, and the others keep sending.

* **Create the workspaces through the API** with an [account key](https://docs.pilotstatus.com.br/api/key-types.md#account-keys) (`ps_account_`, in **Profile → API**): [`POST /v1/workspaces`](https://docs.pilotstatus.com.br/api/workspaces#create-a-workspace). You are the Owner of each one, and the response carries the workspace's primary key. Then act in any of them with the same account key and the `x-workspace-id` header.
* **Once the Pilot Status team marks you as a reseller, every workspace you create is born on Pay As You Go**, billed from the wallet, with **your reseller prices**: the per-number price in your contract and your phone line price. Nothing is charged at creation.
* **Each workspace has its own wallet, its own saved card and its own renewal date** (one month after it was created). Fund each one with [Pix or card through the API](https://docs.pilotstatus.com.br/api/wallet-and-card.md), or link your shared card (below).
* **You can own up to 10 workspaces by default.** Over that, `POST /v1/workspaces` answers `409 WORKSPACE_LIMIT_REACHED` with the `limit`. Ask the Pilot Status team for a higher ceiling.
* **Workspaces you already had keep their plan.** Moving an existing customer to a workspace of their own means connecting their numbers there: a number cannot move between workspaces.

### Shared card

Your **shared card** (or reserve card) is **your card** — the card saved on one of your workspaces — backing your customers' workspaces. **You decide, per workspace, which customers it covers:**

* **The Pilot Status team configures which of your workspaces holds your reserve card.** That setting is what allows you to share it, and it is the source every link points to. Without it, sharing answers `409 SHARED_CARD_NOT_CONFIGURED`.
* **On creation:** send `"shareCard": true` on [`POST /v1/workspaces`](https://docs.pilotstatus.com.br/api/workspaces#create-a-workspace). **With `shareCard` absent (or `false`), the workspace is not shared.** In the dashboard (**Profile → Members → Create another workspace**), the same choice is the **Use my backup card** checkbox, unchecked by default.
* **Afterwards:** [`PUT /v1/workspaces/{id}/shared-card`](https://docs.pilotstatus.com.br/api/workspaces#link-the-shared-card) links a workspace and [`DELETE /v1/workspaces/{id}/shared-card`](https://docs.pilotstatus.com.br/api/workspaces#unlink-the-shared-card) unlinks it. `GET /v1/workspaces` shows each workspace's `sharedCard`.
* **Unlinking makes your card stop paying that customer's renewals.** Use it when a customer stops paying you: from then on, a failed renewal suspends only that customer's workspace.

> [!WARNING]
>
> **Behavior change (2026-10-29).** Before, every workspace a reseller created inherited the shared card automatically. Now a new workspace is shared **only when you ask**: `"shareCard": true` in the API, or the **Use my backup card** checkbox in the dashboard. Workspaces that were already linked stay linked.

The shared card is a backup, not the main payment method:

* **It pays only what the platform charges**: the monthly renewal, extra numbers, phone line purchases and renewals.
* **It is used only when the workspace's wallet does not cover the charge and the workspace has no card of its own.** A card saved on the customer's workspace always comes first.
* **It never pays a top-up.** Nobody in the customer's workspace can spend it on demand: top-ups are paid with Pix, the hosted page or a card typed in at that moment.
* The link is recorded in the workspace's **History** as **Backup card linked** / **Backup card unlinked**.

If you want a customer's failure to pay to suspend only that customer, **do not link the shared card to them** — or unlink it: while linked, their renewals are charged to you.

## WhatsApp connections (numbers)

### When we charge

* **Creating a number or generating its QR / connection link does not charge.** The charge happens at the number's **first connection**. A number that never connected counts neither toward capacity nor toward billing. See [Charged at the first connection](https://docs.pilotstatus.com.br/api/extra-numbers.md#charged-at-the-first-connection).
* **If a connected number goes over the capacity you already paid for, we charge the extra number right away**: the wallet first, then the saved card. The first charge is **prorated** to the days left in your cycle.
* **With no wallet balance and no saved card, creating a number over capacity is refused.**
* **A paid number is good for the whole cycle.** Deleting a number mid-cycle is not refunded, but the slot stays yours until the cycle ends: you can connect another number in it without paying again.
* **On official API (Meta) numbers, conversations and templates are billed by Meta**, straight to the WhatsApp Business account's payment method. That cost does not go through Pilot Status and is not included in any plan.

### The monthly renewal

Resellers are on the **Pay As You Go** plan: no plan fee, you pay per number. The price per number is the one in your contract, and every workspace you create inherits it.

* **On the renewal day, we charge every number that has ever connected and was not deleted**, including the ones that are disconnected on that day.
* **Disconnecting does not stop the charge. Only deleting the number does.** A number you delete before the renewal does not enter the next cycle.
* **There is no capacity to schedule or give back.** To pay less, delete the numbers you no longer want.

See [Pay As You Go works differently](https://docs.pilotstatus.com.br/api/extra-numbers.md#pay-as-you-go-works-differently).

> [!NOTE]
>
> **On the On Demand, Basic, Premium and Enterprise plans the rule is different.** The renewal charges the plan plus the **paid capacity** in extra numbers, even if some of those numbers were deleted. To pay less, **schedule the reduction** with `DELETE /v1/subscription/extra-numbers` (or in the dashboard); it takes effect next cycle. See [Paid capacity is a 30-day entitlement](https://docs.pilotstatus.com.br/api/extra-numbers.md#paid-capacity-is-a-30-day-entitlement).

### When a payment fails

* **Extra-number charge refused at connection:** the number stays connected, but **sending from it is blocked** (`409 NUMBER_BLOCKED`, `reason: "extra_charge_unpaid"`) and the Owner is notified. Topping up the wallet or saving a card retries the charge on its own. You can also pay right away with **Pay now** on the **Numbers** page, or with [`POST /v1/numbers/{id}/pay`](https://docs.pilotstatus.com.br/api/numbers/pay).
* **7 days unpaid:** the number is disconnected, and connecting it again counts as a new first connection, charged again. A Meta Cloud API number is never disconnected: it stays blocked for sending until it is paid.
* **Monthly renewal refused:** there is a **2-day grace period**, with a new attempt every 12 hours. After that, **every number in that workspace stops sending at once**: the API (`422 BILLING_SUSPENDED`), the dashboard chat, Chatwoot and the messages already queued. Numbers stay connected, **receiving keeps working** and inbound webhooks keep arriving. Phone lines are not affected: they have their own billing. Topping up the wallet or saving a card runs the charge again and releases sending.

  > [!WARNING]
  >
  > **What gets suspended is the workspace, not one number.** If all your customers share one workspace and its renewal fails, all of them stop sending at once. Keep [one workspace per end customer](#one-workspace-per-end-customer): then a failed renewal suspends only that customer's numbers.
* **15 days suspended**, on a plan billed from the wallet: the subscription is cancelled and the workspace goes back to the **Free** plan. The Owner is notified by email and WhatsApp. Numbers are not disconnected, but whatever goes over the Free limits is blocked.

### Restoring a deleted number (up to 30 days)

Deleting a number with `DELETE /v1/numbers/{id}` logs the device out right away, but the number stays **30 days in the trash**. Within that window it can be restored with [`POST /v1/numbers/{id}/restore`](https://docs.pilotstatus.com.br/api/numbers/create) (or in the dashboard), with the same id, API keys, webhooks and history. On Pay As You Go:

| When you restore | Charge |
| - | - |
| **In the same cycle**, with its slot still free | **Nothing.** The paid slot is good until the renewal. |
| **In the same cycle**, but the slot was already used by another number | One extra number, **prorated** to the rest of the cycle. |
| **After the renewal** | One extra number, **prorated** to the rest of the cycle. The deleted number was not charged at the renewal and comes back over capacity. |
| A number that **never connected** | **Nothing.** It is charged at its first connection, like any other. |

* **The number comes back disconnected.** Connect it again (`GET /v1/numbers/{id}/connect`, or the Meta flow for an official number). That reconnection does not charge again.
* **If the charge does not go through**, the response is `422`, nothing is charged and the number stays deleted. Retrying the same restore never charges twice.
* **While the number is in the trash, the same phone cannot be created again** (`409 NUMBER_SOFT_DELETED`): restore it or purge it.
* **After 30 days the deletion is final** (`404 RESTORE_WINDOW_EXPIRED`). Purging before that is final too and, on a Meta number, deregisters it at Meta.
* The `number.restored` webhook tells you when a number comes back.

In practice: if your customer paid late, you deleted their number before the renewal and they paid afterwards, restoring costs the prorated rest of the cycle, and you keep their history and settings.

### What your system must record

* **Which workspace belongs to each customer** (its `id`, from `POST /v1/workspaces` or `GET /v1/workspaces`), and **which customer owns each number**, with the **date of its first connection**. The [`number.connected`](https://docs.pilotstatus.com.br/concepts/webhooks) webhook is the trigger: that is when we start billing you, so that is when you start billing your customer. `number.disconnected` tells you when the number dropped.
* **Each workspace's renewal date** with Pilot Status. When one of your customers stops paying, **delete their number before that date**. Disconnecting is not enough. If you do nothing, you pay that customer's next month. (Outside Pay As You Go, delete the number **and** schedule the capacity reduction.)
* **A cancellation rule that follows ours.** We do not refund the cycle in progress. If you refund your customer, the difference comes out of your pocket. The paid slot stays yours until the cycle ends: use it for your next customer.
* **Who pays Meta**, if your customers use the official API: who owns the WhatsApp Business account and which payment method is on it. Put that in your contract with your customer.
* **Numbers blocked for non-payment:** read `extraChargeUnpaidSince` and `extraChargeDisconnectAt` on `GET /v1/numbers` to know what is blocked and when it will be disconnected. See [Pay extra number](https://docs.pilotstatus.com.br/api/numbers/pay.md#how-to-know-a-number-is-blocked).

## Phone lines

### When we charge

* **R\$ 33,90 per month, per line** (US\$ 33.90 on dollar workspaces), on any plan, including Free — unless the Pilot Status team set **your own phone line price**. Then every workspace you create inherits it, and it is the price of every purchase and of every renewal from the next one on. See [Your own phone line price](https://docs.pilotstatus.com.br/phone-lines-pricing.md#your-own-phone-line-price).
* **The purchase charges the whole first month**, with no proration.
* **Each line renews on the same day of the month it was bought**, independent of the plan's and the numbers' cycle. Five lines bought on different days give five renewal dates.
* **Lines use the same wallet as the plan and the numbers.** There is no balance reserved per product: whichever charge comes due first uses the balance first.
* **A line does not count toward the number limit.** If you activate WhatsApp on a line and connect that number to Pilot Status, it is billed like any other number, under the rules in the section above.

### Notices and overdue lines

* **About 48 hours before each renewal**, the holder and the Owner get a notice listing the lines that renew that day and the total.
* **Without a saved card**, there is also a notice when the wallet balance does not cover the renewals of the next 7 days.
* **Renewal refused:** the line stays **2 days** with payment pending (a new attempt every 6 hours), then it is **suspended** and, **1 day** later, **returned to the carrier**. See [Overdue lines](https://docs.pilotstatus.com.br/phone-lines-pricing.md#overdue-lines).
* **Cancelling a line in good standing:** it keeps working until the end of the month already paid, with no refund, and is returned on that day.
* **Holder verification rejected:** lines bought while the verification was under review keep working for 3 days and are then returned. What was paid for them comes back as wallet balance.

> [!WARNING]
>
> **A return cannot be undone.** There is no guarantee you can buy the same number again, and the line's code history is deleted. If a WhatsApp account was activated on the number, whoever rents it next can request a verification code and take over that account. Never let one of your customers' lines lapse without a decision.

### What your system must record

* **Which customer owns each line** and its **purchase date**, because it renews monthly on that date.
* **Bill your customer before the renewal date**, not after. Our grace period is 2 days, and the return is final.
* **Customer in default:** decide **before the line's anniversary** whether you cancel the line or pay one more month for them.
* **Useful webhooks** (see [Phone line webhooks](https://docs.pilotstatus.com.br/api/phone-lines/webhooks.md)): `phone_line.purchased`, `phone_line.renewed`, `phone_line.payment_failed`, `phone_line.suspended`, `phone_line.returned` (with `reason`: `unpaid`, `canceled_by_customer` or `verification_rejected`) and `phone_line.canceled`. Each line also exposes `price` (what its next renewal costs), `amountDue` (what paying an overdue line now charges), `currency` and `currentPeriodEnd` through the [phone lines API](https://docs.pilotstatus.com.br/api/phone-lines/list.md#line-object-fields). The same events reach a [workspace webhook](https://docs.pilotstatus.com.br/api/workspace-webhooks.md).

## Balance

* **Keep in each workspace's wallet, at least**, the line renewals of the next 7 days **plus** the monthly renewal of its numbers.
* **Keep a saved card as a backup** — on the workspace, or your [shared card](#shared-card). It is what prevents blocked sending and returned lines when the wallet does not cover a charge.
* The Owner tops up the wallet in **Plans → Wallet**. Through the API: Pix or a hosted page with [`POST /v1/billing/checkout`](https://docs.pilotstatus.com.br/api/wallet-and-card#top-up-with-pix), or a checkout inside your own app with [Stripe Elements](https://docs.pilotstatus.com.br/guides/transparent-checkout.md). [`wallet.topup_paid`](https://docs.pilotstatus.com.br/api/workspace-webhooks#paid-top-up-event) tells you when the money is in, so you can release your customer's service on your side.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.