Changelog

Fixed

A number bought on a subscription is covered immediately

Provisioning a number on a flat-rate subscription now attaches it to the subscription as part of the same operation, so POST /api/v1/numbers returns a number you can send and call from right away.

Previously coverage was attached only when the prorated subscription invoice was paid. If that purchase raised no invoice — which happens when you hold no numbers, because the subscription already bills a minimum of one — the number stayed uncovered, and every message and call from it failed with subscription_coverage. Releasing your only number and provisioning a replacement hit exactly that case.

Changed

A subscription always bills at least one number

The subscription quantity now tracks your number count with a floor of one, and releasing a number keeps the two in step:

• Releasing a number lowers the quantity by one (prorated by Stripe), but never below one. Releasing your last number leaves the subscription active at the single-number rate instead of cancelling it — cancel with POST /api/v1/billing/subscription/cancel to stop paying.
• While you hold no numbers, the next number you provision is free: the quantity is already at the floor, so no prorated charge is raised. Holding zero numbers and holding one cost the same, and swapping a number costs nothing.
• quantity on subscription in GET /api/v1/billing counts the numbers the subscription covers, so it reads 0 while you hold none. The amount billed is max(quantity, 1) × the unit price.

Previously a release left the quantity untouched, so the subscription kept billing for a number that no longer existed.

iMessage numbers are pay-as-you-go only and never part of a subscription, so none of this applies to them.