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

# Delete Subscription

> Delete a specific subscription by its subscription_id. This stops messages from being sent to that subscription but does not prevent future subscriptions with the same token.

## Overview

Use this API to delete an existing Subscription and its associated properties. Deletion is **asynchronous**, and while the Subscription is being removed, messages will no longer be sent to it.

<Warning>
  This operation only deletes a **single Subscription**. To remove a **user and all their Subscriptions**, use the [Delete User](/reference/delete-user) API instead.
</Warning>

### What Happens When You Delete

* Messages will stop being sent to the deleted subscription.
* **Deleting a Subscription does not block new Subscriptions** with the same `token`.
  * If the app is reopened or a token is re-submitted (e.g., same email or phone), a **new Subscription** may be automatically created.
  * This ensures users can re-subscribe if needed without requiring manual intervention.

***

## How to Use This API

**Required:** `subscription_id`

You must provide the `subscription_id` of the subscription to be deleted. This ID is a UUID generated by OneSignal and is immutable.

To find the `subscription_id`:

1. Use the [View User](/reference/view-user) API.
2. Look at the `subscriptions` array in the response.
3. Identify the correct subscription by its `type`, `token`, or other metadata.
4. Use the corresponding `id` field as the `subscription_id`.

***


## OpenAPI

````yaml DELETE /apps/{app_id}/subscriptions/{subscription_id}
openapi: 3.1.0
info:
  title: api.onesignal.com
  version: '11.6'
servers:
  - url: https://api.onesignal.com
security:
  - {}
paths:
  /apps/{app_id}/subscriptions/{subscription_id}:
    delete:
      summary: Delete subscription
      description: >-
        Delete a specific subscription by its subscription_id. This stops
        messages from being sent to that subscription but does not prevent
        future subscriptions with the same token.
      operationId: delete-subscription
      parameters:
        - name: app_id
          in: path
          description: >-
            Your OneSignal App ID in UUID v4 format. See [Keys &
            IDs](/docs/en/keys-and-ids).
          schema:
            type: string
          required: true
        - name: subscription_id
          in: path
          description: >-
            The unique Subscription ID in UUID v4 format generated by OneSignal.
            See [Subscriptions](/docs/subscriptions).
          schema:
            type: string
          required: true
      responses:
        '202':
          description: '202'
          content:
            application/json:
              examples:
                Result:
                  value: {}
              schema:
                type: object
                properties: {}
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorResponse'
              example:
                errors:
                  - Details about the error.
        '403':
          description: '403'
          content:
            application/json:
              examples:
                Result:
                  value:
                    errors:
                      - Forbidden
              schema:
                $ref: '#/components/schemas/BasicErrorResponse'
        '404':
          description: '404'
          content:
            application/json:
              examples:
                Result:
                  value:
                    errors:
                      - code: subscription-0
                        title: Subscription not found
              schema:
                $ref: '#/components/schemas/StructuredErrorResponse'
        '429':
          description: '429'
          content:
            application/json:
              examples:
                Result:
                  value:
                    errors:
                      - code: Rate Limit Exceeded
                        title: Example error title
                        meta: {}
              schema:
                $ref: '#/components/schemas/StructuredErrorResponse'
          headers:
            Retry-After:
              description: >-
                Number of seconds to wait before retrying the request. Always
                emitted on 429 responses.
              schema:
                type: integer
                minimum: 0
        '503':
          description: >-
            Service temporarily unavailable. Retry after a short backoff. The
            body may be empty or non-JSON in some failure modes.
          headers:
            Retry-After:
              description: >-
                Number of seconds to wait before retrying. Optional — may be
                absent when the response is generated upstream.
              schema:
                type: integer
                minimum: 0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorResponse'
              example:
                errors:
                  - Service temporarily unavailable
      deprecated: false
      security: []
components:
  schemas:
    BasicErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
          description: One or more human-readable error messages.
        success:
          type: boolean
          description: >-
            Present (and `false`) on some endpoints (notifications, templates,
            segments). Not emitted by every endpoint.
        reference:
          type: array
          items:
            type: string
          description: >-
            Documentation URL fragments related to the error. Only emitted by
            the API-key auth error helpers.
    StructuredErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/StructuredErrorItem'
    StructuredErrorItem:
      type: object
      required:
        - code
        - title
      properties:
        code:
          type: string
          description: >-
            Stable error-code identifier. Use this for programmatic branching in
            your integration.
        title:
          type: string
          description: >-
            Human-readable error message intended for logs and operator-facing
            surfaces.
        meta:
          type: object
          additionalProperties: true
          description: >-
            Optional structured details about this specific error. The shape of
            `meta` varies by `code` — for example, the create-user `Conflict`
            code returns `{ conflicting_aliases: { [alias_label]: alias_id } }`.

````