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

# Cancel a subscription

> Schedule an active subscription to cancel at the end of its current billing period.

Authenticate with an API key that belongs to the target organization and has Full access or the `sales:subscriptions:write` permission.

* Cancels at the end of the current billing period. The buyer keeps access until `currentPeriodEnd`, and `cancelAtPeriodEnd` becomes `true`.
* Anyway emails the buyer the cancellation confirmation and sends the usual subscription Webhook. You do not need to send anything.
* Safe to retry: calling it again on a subscription already set to cancel returns `200` with the same body.
* The response is the same subscription object as [Get a subscription record](https://docs.anyway.sh/api-reference/endpoint/get-subscription.md).

| Status | Code | Meaning |
| - | - | - |
| `403` | `INSUFFICIENT_SCOPE` | The key lacks `sales:subscriptions:write`. |
| `404` | | Unknown subscription ID, or it belongs to another organization. |
| `409` | `SUBSCRIPTION_NOT_CANCELABLE` | The subscription is not active (pending, paused, canceled, expired or ended). |
| `500` | `INTERNAL_ERROR` | Something failed on our side. The cancel may have taken effect; retrying is safe. |
| `502` | `PROVIDER_ERROR` | The payment provider call failed. The cancel may not have taken effect; retrying is safe. |


## OpenAPI

````yaml api-reference/openapi.json POST /v1/subscriptions/{id}/cancel
openapi: 3.0.3
info:
  description: >-
    Organization-scoped commerce API for merchant backends: create and manage
    checkout sessions, and query commerce records.
  title: Anyway Merchant API
  contact: {}
  version: '1.0'
  x-source: anyway-backend-go
servers:
  - url: https://merchant-api-prod.anyway.sh
security: []
paths:
  /v1/subscriptions/{id}/cancel:
    post:
      tags:
        - subscriptions
      summary: Cancel a subscription at period end
      description: >-
        Cancels an active subscription at the end of the current billing period;
        the buyer keeps access until `currentPeriodEnd`. Calling it again on a
        subscription already set to cancel returns 200 with the same body.
        Requires Full access or the `sales:subscriptions:write` permission.
      parameters:
        - description: Subscription ID
          name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/response.ApiResponse-merchantapi_SubscriptionResponse
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.ApiResponse-any'
        '403':
          description: >-
            Forbidden. The API key lacks the required permission
            (INSUFFICIENT_SCOPE).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.ApiResponse-any'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.ApiResponse-any'
        '409':
          description: >-
            Conflict. The subscription is not active
            (SUBSCRIPTION_NOT_CANCELABLE).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.ApiResponse-any'
        '500':
          description: >-
            Internal Server Error (INTERNAL_ERROR). The cancel may have taken
            effect; retrying is safe.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.ApiResponse-any'
        '502':
          description: >-
            Bad Gateway. The payment provider call failed (PROVIDER_ERROR); the
            cancel may not have taken effect, retrying is safe.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.ApiResponse-any'
      security:
        - APIKeyAuth: []
components:
  schemas:
    response.ApiResponse-merchantapi_SubscriptionResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/merchantapi.SubscriptionResponse'
        error:
          $ref: '#/components/schemas/response.ErrorDetail'
        message:
          type: string
        success:
          type: boolean
    response.ApiResponse-any:
      type: object
      properties:
        data: {}
        error:
          $ref: '#/components/schemas/response.ErrorDetail'
        message:
          type: string
        success:
          type: boolean
    merchantapi.SubscriptionResponse:
      type: object
      properties:
        amountCents:
          type: integer
        billingInterval:
          type: string
          enum:
            - DAY
            - MONTH
            - YEAR
        cancelAtPeriodEnd:
          type: boolean
        canceledAt:
          type: string
        createdAt:
          type: string
        currency:
          type: string
        currentPeriodEnd:
          type: string
        customerEmail:
          type: string
        customerId:
          type: string
        endedAt:
          type: string
        id:
          description: 'Deprecated: use subscriptionId.'
          type: string
          deprecated: true
        initialOrderId:
          type: string
        latestOrderId:
          type: string
        productId:
          type: string
        productName:
          type: string
        status:
          type: string
        subscriptionId:
          type: string
        updatedAt:
          type: string
    response.ErrorDetail:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
  securitySchemes:
    APIKeyAuth:
      description: 'Merchant API key (format: ak_BASE64)'
      type: apiKey
      name: X-API-Key
      in: header

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.