> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobilerun.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cancel a phone-number purchase or an active rental

> Cancels a Mobilerun Phone. The outcome depends on the number's current state:

- If the number is still awaiting payment and no payment for it is currently being processed, the checkout is closed immediately and the number is retired.
- If the number is on the standard paid plan and already paid and in service, cancellation is scheduled for the end of the current billing period rather than taking effect immediately. The number stays usable through the period already paid for, with no partial refund. Calling this again while a cancellation is already scheduled is a no-op that returns the same result. The response's `state` reflects this as `cancel_scheduled` with `cancelAtPeriodEnd: true`; `currentPeriodEnd` is populated once billing confirms the cancellation.

Any other state (already refunding, a permanent billing failure, a payment currently being processed, an included-plan number, or a non-hosted/BYO number) returns 409 `not_cancellable`. Returns 404 if the number doesn't exist or isn't owned by the caller.



## OpenAPI

````yaml /api-reference/mobilerun-numbers.yaml delete /numbers/phones/{id}
openapi: 3.1.0
info:
  title: Mobilerun Numbers
  version: v1
servers:
  - description: Droidrun Cloud API
    url: https://api.mobilerun.ai/v1
security:
  - bearerAuth: []
paths:
  /numbers/phones/{id}:
    delete:
      tags:
        - Numbers
      summary: Cancel a phone-number purchase or an active rental
      description: >-
        Cancels a Mobilerun Phone. The outcome depends on the number's current
        state:


        - If the number is still awaiting payment and no payment for it is
        currently being processed, the checkout is closed immediately and the
        number is retired.

        - If the number is on the standard paid plan and already paid and in
        service, cancellation is scheduled for the end of the current billing
        period rather than taking effect immediately. The number stays usable
        through the period already paid for, with no partial refund. Calling
        this again while a cancellation is already scheduled is a no-op that
        returns the same result. The response's `state` reflects this as
        `cancel_scheduled` with `cancelAtPeriodEnd: true`; `currentPeriodEnd` is
        populated once billing confirms the cancellation.


        Any other state (already refunding, a permanent billing failure, a
        payment currently being processed, an included-plan number, or a
        non-hosted/BYO number) returns 409 `not_cancellable`. Returns 404 if the
        number doesn't exist or isn't owned by the caller.
      operationId: cancelNumber
      parameters:
        - in: path
          name: id
          required: true
          schema:
            example: 550e8400-e29b-41d4-a716-446655440000
            format: uuid
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/PublicNumber'
                required:
                  - data
                type: object
          description: Number cancelled
        '401':
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                required:
                  - error
                type: object
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberErrorResponse'
          description: Conflict — see `reason` for the stable, machine-readable cause
        '500':
          description: Internal Server Error
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberErrorResponse'
          description: >-
            Service Unavailable — phone numbers are disabled for this deployment
            (see `reason`)
      x-codeSamples:
        - lang: JavaScript
          source: >-
            import Mobilerun from '@mobilerun/sdk';


            const client = new Mobilerun({
              apiKey: process.env['MOBILERUN_CLOUD_API_KEY'], // This is the default and can be omitted
            });


            const number = await
            client.numbers.delete('550e8400-e29b-41d4-a716-446655440000');


            console.log(number.data);
        - lang: Python
          source: |-
            import os
            from mobilerun_sdk import Mobilerun

            client = Mobilerun(
                api_key=os.environ.get("MOBILERUN_CLOUD_API_KEY"),  # This is the default and can be omitted
            )
            number = client.numbers.delete(
                "550e8400-e29b-41d4-a716-446655440000",
            )
            print(number.data)
components:
  schemas:
    PublicNumber:
      properties:
        canSend:
          type: boolean
        cancelAtPeriodEnd:
          type: boolean
        cancellable:
          type: boolean
        capabilities:
          items:
            enum:
              - sms
              - voice
            type: string
          type:
            - array
            - 'null'
        checkoutUrl:
          type:
            - string
            - 'null'
        countryCode:
          type:
            - string
            - 'null'
        createdAt:
          format: date-time
          type:
            - string
            - 'null'
        currentPeriodEnd:
          format: date-time
          type:
            - string
            - 'null'
        id:
          format: uuid
          type: string
        label:
          type:
            - string
            - 'null'
        phoneNumber:
          type:
            - string
            - 'null'
        purpose:
          type:
            - string
            - 'null'
        state:
          enum:
            - awaiting_payment
            - provisioning
            - active
            - cancel_scheduled
            - expired
            - failed
          type: string
        updatedAt:
          format: date-time
          type:
            - string
            - 'null'
      required:
        - id
        - phoneNumber
        - label
        - state
        - countryCode
        - capabilities
        - canSend
        - purpose
        - checkoutUrl
        - currentPeriodEnd
        - cancelAtPeriodEnd
        - cancellable
        - createdAt
        - updatedAt
      type: object
    NumberErrorResponse:
      properties:
        message:
          type: string
        reason:
          enum:
            - product_disabled
            - not_cancellable
          type: string
        success:
          enum:
            - false
          type: boolean
      required:
        - success
        - reason
        - message
      type: object
  securitySchemes:
    bearerAuth:
      bearerFormat: Opaque
      description: Bearer token via Authorization header
      scheme: bearer
      type: http

````