Cancel a phone line

DELETE /v1/phone-lines/{id} cancels a line and answers the line as it is afterwards. What happens depends on the line’s status.

Requires a tenant-scoped key. With an OAuth / MCP token, only the workspace Owner may cancel (phone_lines:cancel) — 403 PERMISSION_DENIED otherwise.

Endpoint

DELETE https://pilotstatus.com.br/v1/phone-lines/{id} No body. {id} is the line’s id, not the phone number.

What happens, by status

`status` before	Result	Response
`ACTIVE`	Cancelled at period end, no refund. The line stays `ACTIVE` and fully usable — activation codes included — until `currentPeriodEnd`. It is not renewed, and becomes `CANCELED` when the period ends.	`200`, `status: "ACTIVE"`, `cancelAtPeriodEnd: true`
`ACTIVE`, already cancelled	Nothing changes — calling again is safe.	`200`, same line
`PAYMENT_PENDING`, `SUSPENDED`	Returned immediately. There is no paid period left, so the number goes back to the carrier’s pool now. Irreversible.	`200`, `status: "RETURNED"`
`RETURNED`, `CANCELED`	Refused — the line is already finished.	`409 NOT_CANCELABLE`

A returned number stops being yours for good: nothing undoes a return, and there is no guarantee you can ever get it again. The WhatsApp account activated on it stays tied to that number — whoever rents it next can request a verification code for it. Cancelling an unpaid line does this at once, with no grace period.

If a return of the same unpaid line is already under way — started by the hourly billing run or by the dashboard’s Choose which lines to keep — the call answers 200 with the line as it stands, possibly still PAYMENT_PENDING or SUSPENDED, and that process completes the return. Read the line again to confirm RETURNED. Changed your mind about an ACTIVE line? Undoing a scheduled cancellation is available in the dashboard only, to the workspace Owner (Phone lines → the line → Undo cancellation), while the line is still ACTIVE.

Example

curl -X DELETE "https://pilotstatus.com.br/v1/phone-lines/cmg5k2l1n0001pl8example9x" \
  -H "x-api-key: ps_your_tenant_scoped_key"

{
  "line": {
    "id": "cmg5k2l1n0001pl8example9x",
    "number": "551148637200",
    "display": "(11) 4863-7200",
    "ddd": "11",
    "status": "ACTIVE",
    "price": 33.9,
    "currency": "BRL",
    "purchasedAt": "2026-10-01T14:03:11.000Z",
    "currentPeriodEnd": "2026-11-01T14:03:11.000Z",
    "cancelAtPeriodEnd": true,
    "paymentPendingSince": null,
    "suspendedAt": null,
    "returnedAt": null,
    "canceledAt": null,
    "activationCount": 1
  }
}

The body is the line object.

Events

A line cancelled at period end sends phone_line.canceled when it becomes CANCELED — usually within about an hour after currentPeriodEnd; if the carrier does not confirm, it is retried at each hourly run.
An unpaid line returned by this call sends phone_line.returned right away.

See Phone line webhooks.

Errors

Status	`code`	Meaning
`401`	—	Missing or invalid credential.
`403`	`NUMBER_SCOPE_NOT_ALLOWED`	Number-scoped key (or per-number OAuth grant). Use the tenant-scoped key.
`403`	`WORKSPACE_MEMBERSHIP_REQUIRED`	OAuth / MCP token of a user who is no longer an active member.
`403`	`PERMISSION_DENIED`	OAuth / MCP token of a user who is not the workspace Owner.
`404`	`LINE_NOT_FOUND`	No such line in your workspace. A line of another workspace answers the same, and is left untouched.
`409`	`NOT_CANCELABLE`	The line is already `RETURNED` or `CANCELED`.
`503`	`SUPPLIER_UNAVAILABLE`	Unpaid line only: the carrier did not confirm the return. This call did not change the line — retry in a few minutes.
`500`	`INTERNAL_ERROR`	Unexpected failure.

Overview

Messaging

Templates

Numbers

Phone Lines

Conversations & Data

Webhooks

Voice Calls

API Layer

Account & Billing

Branding & Embedding

DELETE /v1/phone-lines/{id} — Cancel a Line

Cancel a phone line

Endpoint

What happens, by status

Example

Events

Errors

​Cancel a phone line

​Endpoint

​What happens, by status

​Example

​Events

​Errors

Cancel a phone line

Endpoint

What happens, by status

Example

Events

Errors