---
title: "Delete purchased numbers"
method: DELETE
path: "/api/v2/numbers/purchase"
tags: ["Numbers & Inventory"]
---

# Delete purchased numbers

`DELETE /api/v2/numbers/purchase`

## Request

- Base URL: `https://app.didlogic.com`
- URL: `https://app.didlogic.com/api/v2/numbers/purchase`
- Auth: HTTP bearer

Cancel purchase of DID numbers and return them to inventory.

**Important notes:**
- Can cancel multiple numbers in a single request
- Numbers are returned to seller's inventory
- Optional quarantine period before number becomes available again
- Refund policy depends on service terms

**When to use:**
- User wants to cancel number purchase
- Returning numbers after unsuccessful activation
- Bulk number release

**Partial cancellation:** Numbers not present in your cancelable inventory
are skipped (not cancelled) and reported in the `warnings` array with code
`not_in_inventory`. If none of the requested numbers are cancelable, the
request returns `422`.

A number that is cancelable but whose cancellation fails is reported with
code `cancellation_failed` and is omitted from `dids`; it remains in your
inventory and is still billable. A request where every number fails this
way returns `200` with an empty `dids` array.

## Query parameters

- `id_in[]` integer[]
- `did_numbers[]` string[]

## Response `200`

cancels owned numbers and reports skipped ones as warnings

- object
  - `dids` object[], required: List of cancelled DIDs returned to inventory
    - `id` integer, required: DID identifier
    - `number` string, required: Phone number
    - `sms_enabled` boolean, required: Whether SMS is enabled
    - `no_local_cli` boolean, required: Whether local caller ID is disabled
    - `channels` integer, required: Maximum simultaneous calls
    - `country` string, required: Country name
    - `area` string, required: City/area name
    - `free_minutes` integer, required: Free minutes included per month
    - `codec` unknown, required
    - `require_docs` string, required: Comma-separated list of required document type IDs: 1 - Personal ID, 2 - Proof of Address, 3 - Proof of Local Address, 4 - Business Registration, 5 - Local Business Registration, 6 - Letter of Intent
    - `commitment_months` integer, required: Minimum service term in months
    - `never_sold` integer, required: Whether number has never been sold before (1=yes, 0=no)
    - `activation` number, float, required: One-time activation fee (USD)
    - `monthly_fee` number, float, required: Monthly recurring fee (USD)
    - `per_minute` number, float, required: Per-minute inbound call rate (USD)
    - `origination_per_min` number, float, required: Per-minute origination rate (USD)
  - `warnings` Warning[]: Non-fatal notices for requested numbers that were not cancelled — either not in your cancelable inventory (`not_in_inventory`) or cancelable but not cancelled (`cancellation_failed`). Present only when non-empty.
    - `resource` string, required: Entity kind the warning is about (e.g. "caller_id", "did").
    - `identifier` string, required: The value the client sent that was skipped.
    - `code` string, required: Stable machine-readable token for the reason.
    - `message` string, required: Human-readable explanation.

## Other responses

- `401`: returns unauthorized
- `403`: returns forbidden
- `422`: returns unprocessable entity

---

[API](https://skmtc.dev/didlogic/apis/get-started.md) · [All operations](https://skmtc.dev/didlogic/apis/get-started/llms.txt) · [OpenAPI document](https://skmtc.dev/didlogic/apis/get-started/revisions/dc972d592b34?raw)