> ## 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:
  - url: https://api.mobilerun.ai
    description: Droidrun Cloud API
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:
        - schema:
            type: string
            format: uuid
            example: 550e8400-e29b-41d4-a716-446655440000
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Number cancelled
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PublicNumber'
                required:
                  - data
        '401':
          description: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
        '409':
          description: Conflict — see `reason` for the stable, machine-readable cause
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberErrorResponse'
        '500':
          description: Internal Server Error
        '503':
          description: >-
            Service Unavailable — phone numbers are disabled for this deployment
            (see `reason`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberErrorResponse'
components:
  schemas:
    PublicNumber:
      type: object
      properties:
        id:
          type: string
          format: uuid
        phoneNumber:
          type:
            - string
            - 'null'
        state:
          type: string
          enum:
            - awaiting_payment
            - provisioning
            - active
            - cancel_scheduled
            - expired
            - failed
        countryCode:
          type:
            - string
            - 'null'
        capabilities:
          type:
            - array
            - 'null'
          items:
            type: string
            enum:
              - sms
              - voice
        canSend:
          type: boolean
        purpose:
          type:
            - string
            - 'null'
        checkoutUrl:
          type:
            - string
            - 'null'
        currentPeriodEnd:
          type:
            - string
            - 'null'
          format: date-time
        cancelAtPeriodEnd:
          type: boolean
        cancellable:
          type: boolean
        createdAt:
          type:
            - string
            - 'null'
          format: date-time
        updatedAt:
          type:
            - string
            - 'null'
          format: date-time
      required:
        - id
        - phoneNumber
        - state
        - countryCode
        - capabilities
        - canSend
        - purpose
        - checkoutUrl
        - currentPeriodEnd
        - cancelAtPeriodEnd
        - cancellable
        - createdAt
        - updatedAt
    NumberErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - false
        reason:
          type: string
          enum:
            - product_disabled
            - not_cancellable
        message:
          type: string
      required:
        - success
        - reason
        - message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Opaque
      description: Bearer token via Authorization header

````