​

Extra numbers & On Demand

​

Charged at the first connection

• Creating a number charges nothing. Neither does generating a pairing link.
• A number that never connected does not count toward your capacity or your monthly bill. You pay only for the numbers that were actually paired.
• On a paid plan the charge is automatic. It is the same purchase as POST /v1/subscription/extra-numbers for one number: prorated for the days left in the cycle, wallet credits first, the remainder on the saved card. The Free plan never buys by itself — see Free plan.
• Buying ahead still works. A number that connects within the capacity you already paid for is not charged again.
• For an unofficial number the first connection is the first time its QR code or pairing code is completed. For an official (Meta Cloud API) number it is when the number is activated — for example, when the Embedded Signup finishes.

​

Free plan

• Creating a number past the plan’s allowance is refused with 402 PLAN_NUMBER_LIMIT_REACHED, even when the workspace has wallet balance or a saved card. On the paid plans, funds let the creation through and the extra is charged at the first connection.
• Pairing a number that never connected is refused too when the plan’s allowance is already full. GET /v1/numbers/{id}/connect, the connect step of a remote pairing link, and POST /v1/numbers/remote-pairing for a phone that already exists answer 402 PLAN_NUMBER_LIMIT_REACHED. Re-pairing a number that had already connected is never refused.
• If a second number connects anyway — two pairings started side by side — nothing is charged and the plan does not change. The number stays connected with sending blocked (409 NUMBER_BLOCKED, reason: "extra_charge_unpaid"), and POST /v1/numbers/{id}/pay answers 402 PLAN_NUMBER_LIMIT_REACHED for it. A top-up or a saved card does not lift this block.

​

When the charge is refused

• POST /v1/messages/send answers 409 NUMBER_BLOCKED with reason: "extra_charge_unpaid".
• A message that was already queued fails, and shows NUMBER_BLOCKED in the logs.
• GET /v1/numbers and GET /v1/numbers/{id} show extraChargeUnpaidSince on the number.

{
  "error": "This number's extra-number charge is unpaid. Pay it to resume sending from this number. | A cobrança do número extra deste número está pendente. Pague para voltar a enviar por ele.",
  "code": "NUMBER_BLOCKED",
  "reason": "extra_charge_unpaid",
  "observedAt": "2026-10-10T12:00:00.000Z"
}

​

What lifts the block

​

After 7 days unpaid

• A number connected by QR code that stays unpaid for 7 days is disconnected: its device is logged out and the number stops counting toward your capacity. A reminder is sent 2 days before, and extraChargeDisconnectAt on the number tells you when. Connecting it again is a new first connection, charged again.
• A Meta Cloud API number is never disconnected. It stays blocked for sending until it is paid.

​

GET /v1/subscription/extra-numbers — Preview (dry-run)

curl "https://pilotstatus.com.br/v1/subscription/extra-numbers?quantity=1" \
  -H "x-api-key: ps_your_tenant_scoped_key"

{
  "plan": "FREE",
  "requiresConversion": true,
  "explanation": { "pt": "…", "en": "…" },
  "currentNumbers": 1,
  "requested": 1,
  "billedQuantity": 2,
  "currency": "BRL",
  "unitPriceMonthly": 29.9,
  "proratedUnitPrice": 14.95,
  "proratedTotal": 29.9,
  "remainingDays": 15,
  "totalDaysInCycle": 30,
  "walletBalance": 0,
  "hasSavedCard": false,
  "fundingSource": "none",
  "canFund": false,
  "unitPriceBRL": 29.9,
  "monthlyTotalBRL": 59.8
}

​

POST /v1/subscription/extra-numbers — Buy

curl -X POST "https://pilotstatus.com.br/v1/subscription/extra-numbers" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_tenant_scoped_key" \
  -d '{ "quantity": 1, "confirm": true }'

• Free → On Demand conversion. If you are on the Free plan, buying an extra number moves you to On Demand: your current (formerly free, 200-message-limited) number becomes a paid, unlimited number and the new number is billed too. So buying 1 extra while Free bills you for 2 numbers. Because this changes what you pay, the POST returns 409 CONFIRMATION_REQUIRED (with the preview) unless you send confirm: true.
• Already On Demand / paid. Buying increments your number count; messages stay unlimited.
• Payment. The prorated cost is charged on the spot: from your prepaid wallet first, then any remainder from your saved card (dashboard Plans → Cartão, or POST /v1/billing/checkout with add_card). A successful purchase answers { "success": true, "charged": true, … } — creditsUsed and cardCharged show how the charge was split, and paidExtraNumbers already includes the new slot, so you can create the number with POST /v1/numbers right away. This route never returns a checkout link (there is no checkoutUrl, and charged is never false): with neither enough credits nor a saved card it returns 402 INSUFFICIENT_FUNDS — nothing is charged, and any credits it had started to use are put back. Top up or save a card, then retry.
• The monthly recurrence comes out of the wallet, not a separate subscription. Each cycle, paidExtraNumbers × unit price is debited from your credits, falling back to your saved card. Top the wallet up with POST /v1/billing/checkout (wallet_topup, card only) or in the dashboard, where PIX is also available — so you can run On Demand on PIX credits topped up in the dashboard and never save a card.

​

When the payment does not go through

{
  "error": "Saldo insuficiente na carteira e cartão indisponível para cobrar o número extra. Adicione créditos ou um cartão.",
  "code": "INSUFFICIENT_FUNDS",
  "proratedTotal": 29.9,
  "currency": "BRL",
  "walletReason": "NO_CARD"
}

​

The declineCode field

• Treat code: "PAYMENT_FAILED" as the decision. It is always present and always means the same thing.
• Use declineCode only to refine the message when it is there.
• Never read “no declineCode” as “not a decline” — and never as “the card is fine”.

​

Paid capacity is a 30-day entitlement

• Deleting a number does not reduce your paid capacity. DELETE /v1/numbers/<id> frees the slot so you can reconnect a different number in the same cycle — your paid count and your bill stay the same until the cycle ends.
• Reducing capacity is an explicit, scheduled action. You decide to lower the number of paid slots; the change takes effect at the next cycle, when billing drops to the new amount. Nothing is refunded for the running cycle.

​

Pay As You Go works differently

• A number is charged when it first connects, prorated for the days left in the cycle — the same rule as on every plan, described above. For an unofficial number that is the first connection; for an official (Meta) number it is when the Embedded Signup finishes.
• The slot you paid for lasts the cycle. Deleting a number and connecting another one in its place does not charge again.
• The next cycle bills only what is still connected. Nothing accumulates from the previous cycle, so there is nothing to schedule down — see the 409 NOT_APPLICABLE_FOR_PLAN on the endpoint below.
• A pairing you never finished is not a number and is not billed. The “awaiting connection” row that appears while your end user is inside the Facebook dialog is excluded from billing and from your capacity, and it is removed automatically 24h after it was created.

​

DELETE /v1/subscription/extra-numbers — Schedule a reduction

curl -X DELETE "https://pilotstatus.com.br/v1/subscription/extra-numbers" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_tenant_scoped_key" \
  -d '{ "quantity": 1 }'

• Scheduled, not immediate. This cycle keeps the current capacity (no refund); the reduction applies at the next rollover, when future months bill less.
• Editable. Calling again overwrites the scheduled target. Cancel it with DELETE …/schedule (below).
• Cannot drop below connected numbers. If the target would leave your limit under the numbers you still have connected, it returns 409 NUMBER_LIMIT_EXCEEDED ({ currentNumberCount, maxNumbers }) — delete a number first.
• Not available on Pay As You Go. Returns 409 NOT_APPLICABLE_FOR_PLAN. There is no paid capacity to give back: Pay As You Go bills the numbers you have connected, and the next cycle already charges only what stayed connected. To pay less, delete the number — scheduling nothing is required.
• quantity defaults to 1 and is clamped so you never go below 0 paid extras. Number-scoped keys get 403.

{
  "success": true,
  "charged": true,
  "plan": "ON_DEMAND",
  "paidExtraNumbers": 5,
  "scheduledPaidExtraNumbers": 4,
  "scheduledReductionEffectiveAt": "2026-08-01T00:00:00.000Z",
  "maxNumbers": 5
}

​

DELETE /v1/subscription/extra-numbers/schedule — Cancel the scheduled reduction

curl -X DELETE "https://pilotstatus.com.br/v1/subscription/extra-numbers/schedule" \
  -H "x-api-key: ps_your_tenant_scoped_key"

​

POST /v1/billing/checkout — Wallet top-up / add a card

curl -X POST "https://pilotstatus.com.br/v1/billing/checkout" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_tenant_scoped_key" \
  -d '{ "purpose": "wallet_topup", "amount": 50 }'

• purpose: "wallet_topup" — top up the prepaid wallet. Card only: the hosted Stripe checkout offers no PIX — PIX top-ups exist only in the dashboard (BRL accounts). Requires amount: a positive number, in your account currency (the wallet’s BRL or USD — it cannot be chosen per request). Missing, zero, negative or non-numeric returns 400 { "error": "amount must be a positive number", "code": "INVALID_AMOUNT" }.
• purpose: "add_card" — save a card for future On Demand charges.

{
  "url": "https://checkout.stripe.com/c/pay/cs_test_…",
  "purpose": "wallet_topup",
  "orderId": "…",
  "amount": 50,
  "currency": "BRL"
}