# Switch auto-renew on a phone number (/docs/api-reference/phone-numbers/setPhoneNumberAutoRenew)

> Turn auto-renew off or back on for a number bought from the number shop. With auto-renew off, the number is not charged again: it keeps working until the end of the period already paid for and is then released. Turn it back on before that date and it renews as normal. Sending the value the number already has changes nothing and still succeeds.

With auto-renew off, the number is never charged again. It keeps working until the end of the
period already paid for, and is released within a few hours after that. About 48 hours before,
the account owner gets an email saying the number will be released, and another once it is.

Turn it back on any time before that date and the number renews as normal. Once released, the
number is gone. Every new purchase starts with auto-renew on, including buying back a number
you let go.

More in [Buy a number over the API](/docs/buy-a-number-api#stop-a-number-renewing).

**POST** `/phone_number/auto_renew`

Turn auto-renew off or back on for a number bought from the number shop.
With auto-renew off, the number is not charged again: it keeps working
until the end of the period already paid for and is then released. Turn
it back on before that date and it renews as normal. Sending the value
the number already has changes nothing and still succeeds.

```yaml
operationId: setPhoneNumberAutoRenew
requestBody:
  required: true
  content:
    application/json:
      schema:
        type: object
        required:
          - phone_number
          - auto_renew
        properties:
          phone_number:
            type: string
            description: The number to switch.
            example: '+15551234567'
          auto_renew:
            type: boolean
            description: >-
              `false` stops renewal, `true` turns it back on. Must be a JSON boolean: a string such
              as `"false"`, a number, or a missing value is refused.
            example: false
          user_id:
            type: integer
            description: 'Reseller accounts only: the client to act on. Omit it to act on your own account.'
      example:
        phone_number: '+15551234567'
        auto_renew: false
responses:
  '200':
    description: The switch is set.
    content:
      application/json:
        schema:
          type: object
          properties:
            success:
              type: boolean
            phone_number:
              type: string
            auto_renew:
              type: boolean
              description: The value the number now has.
        example:
          success: true
          phone_number: '+15551234567'
          auto_renew: false
  '400':
    description: |
      `phone_number` is missing, or `auto_renew` is not `true` or `false`.
    content:
      application/json:
        schema:
          type: object
          properties:
            error:
              type: string
              description: Machine-readable error code.
            error_description:
              type: string
              description: Human-readable explanation.
            code:
              type: string
              description: |
                Stable, specific reason. Present on the newer endpoints (Voice
                cloning, WhatsApp); older endpoints return only `error`.
            request_id:
              type: string
              description: |
                Correlates this response with the server log. Present alongside
                `code`. Also sent as the `X-Request-Id` header.
        example:
          error: invalid_request
          error_description: auto_renew must be true or false.
  '401':
    description: Missing or invalid API key.
  '403':
    description: |
      A `user_id` was sent by a key that is not a reseller admin, or
      the named client's account is currently unavailable.
    content:
      application/json:
        schema:
          type: object
          properties:
            error:
              type: string
              description: Machine-readable error code.
            error_description:
              type: string
              description: Human-readable explanation.
            code:
              type: string
              description: |
                Stable, specific reason. Present on the newer endpoints (Voice
                cloning, WhatsApp); older endpoints return only `error`.
            request_id:
              type: string
              description: |
                Correlates this response with the server log. Present alongside
                `code`. Also sent as the `X-Request-Id` header.
        example:
          error: forbidden
          error_description: Access denied. Only reseller accounts can use this endpoint.
  '404':
    description: |
      The `user_id` did not name one of your clients (`not_found`),
      or the account holds no such number (`number_not_found`).
    content:
      application/json:
        schema:
          type: object
          properties:
            error:
              type: string
              description: Machine-readable error code.
            error_description:
              type: string
              description: Human-readable explanation.
            code:
              type: string
              description: |
                Stable, specific reason. Present on the newer endpoints (Voice
                cloning, WhatsApp); older endpoints return only `error`.
            request_id:
              type: string
              description: |
                Correlates this response with the server log. Present alongside
                `code`. Also sent as the `X-Request-Id` header.
        example:
          error: number_not_found
          error_description: No such number on this user.
  '422':
    description: |
      The number was not bought from the number shop, for example a number
      imported from Twilio, Exotel, or a SIP trunk. Only shop numbers renew.
    content:
      application/json:
        schema:
          type: object
          properties:
            error:
              type: string
              description: Machine-readable error code.
            error_description:
              type: string
              description: Human-readable explanation.
            code:
              type: string
              description: |
                Stable, specific reason. Present on the newer endpoints (Voice
                cloning, WhatsApp); older endpoints return only `error`.
            request_id:
              type: string
              description: |
                Correlates this response with the server log. Present alongside
                `code`. Also sent as the `X-Request-Id` header.
        example:
          error: not_renewable
          error_description: Auto renew applies only to a number bought from the shop.
  '500':
    description: Unexpected server error.
    content:
      application/json:
        schema:
          type: object
          properties:
            error:
              type: string
              description: Machine-readable error code.
            error_description:
              type: string
              description: Human-readable explanation.
            code:
              type: string
              description: |
                Stable, specific reason. Present on the newer endpoints (Voice
                cloning, WhatsApp); older endpoints return only `error`.
            request_id:
              type: string
              description: |
                Correlates this response with the server log. Present alongside
                `code`. Also sent as the `X-Request-Id` header.
            ref:
              type: string
              description: Reference to quote to support.
        example:
          error: server_error
          error_description: >-
            Something went wrong on our side. Please try again shortly, or contact support with
            reference a1b2c3d4e5f6.
          ref: a1b2c3d4e5f6
```

**cURL**

```bash
# Stop renewing a number. It keeps working until its paid period ends.
curl -X POST "https://omnidim.io/api/v1/phone_number/auto_renew" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+15551234567",
    "auto_renew": false
  }'
```

**curl**

```bash
curl -X POST "https://omnidim.io/api/v1/phone_number/auto_renew" \
  -H "Authorization: Bearer $OMNIDIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "phone_number": "+15551234567",
  "auto_renew": false
}'
```