Skip to navigation

Release a phone number

View as Markdown

Release a number — standard SMS/call or iMessage. Immediate and irreversible.

On a flat-rate subscription, releasing a number lowers the subscription quantity by one and Stripe prorates the change — but the quantity never falls below one number. Releasing your last number therefore leaves the subscription active at the single-number rate rather than cancelling it, and the next number you provision is free (see Provision a phone number). To stop paying entirely, cancel the subscription with Cancel the subscription at period end.

Releasing a number also releases every number it replaced (see replaces). A replaced number can’t be released on its own.

Authentication

AuthorizationBearer

Your Dial API key, sent as Authorization: Bearer sk_live_...

Path parameters

idstringRequired

Response

Released.
successbooleanOptional

Errors

401
Unauthorized Error
404
Not Found Error
409
Conflict Error