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

# Stop or resume renewal

> Schedule or reverse end-of-cycle cancellation for a paid subscription.

Pass the exact opaque `customerId` as a URL-encoded query value and the numeric `subscriptionId` from [List customer subscriptions](https://docs.integrateledger.com/api-reference/customers/subscriptions.md). Set `cancelAtPeriodEnd` to `true` to stop the next renewal or `false` to resume it before the period ends. Retrying the same desired state is safe. Ledger verifies that the Stripe subscription belongs to this customer, organization, environment, and plan before changing it.

Stopping renewal does not refund the current period. The plan and its remaining plan credits stay available until the paid period ends; purchased credit packs are unaffected. Resuming restores future monthly billing. A pending plan upgrade or a Stripe pause, schedule, custom cancellation date, or mismatched subscription blocks the change. Stripe unavailability returns an error rather than guessing the state.

This endpoint manages an active paid subscription. It does not cancel an unpaid Checkout link. Use [Billing and Checkout](https://docs.integrateledger.com/billing.md) for payment timing and [List customer purchases](https://docs.integrateledger.com/api-reference/customers/purchases.md) for credit packs.


## OpenAPI

````yaml openapi.json PUT /v1/customers/subscriptions/{subscriptionId}/cancellation
openapi: 3.1.0
info:
  title: Ledger API
  version: 0.1.0
servers:
  - url: https://api.integrateledger.com
    description: Hosted Ledger API
security: []
paths:
  /v1/customers/subscriptions/{subscriptionId}/cancellation:
    put:
      tags:
        - Customers
      summary: Stop or resume a paid subscription's renewal
      operationId: setSubscriptionCancellation
      parameters:
        - schema:
            type: integer
            exclusiveMinimum: 0
            maximum: 2147483647
          required: true
          name: subscriptionId
          in: path
        - schema:
            type: string
            minLength: 1
            maxLength: 255
          required: true
          name: customerId
          in: query
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomerSubscriptionCancellationInput'
      responses:
        '200':
          description: Paid subscription renewal setting
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/UpdateCustomerSubscriptionCancellationResponse
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerError'
        '401':
          description: Missing or invalid Ledger API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerError'
        '404':
          description: Subscription not found for this customer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerError'
        '409':
          description: Subscription cannot safely change renewal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerError'
        '422':
          description: Organization Stripe connection unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerError'
        '502':
          description: Stripe unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerError'
      security:
        - ApiKey: []
      x-codeSamples:
        - lang: bash
          label: cURL
          source: >-
            curl --request PUT
            'https://api.integrateledger.com/v1/customers/subscriptions/42/cancellation?customerId=user_123'
            \
              -H "Authorization: Bearer $LEDGER_API_KEY" \
              -H 'Content-Type: application/json' \
              --data '{"cancelAtPeriodEnd":true}'
        - lang: python
          label: Python SDK (source only)
          source: >-
            import os

            from ledger_sdk import Ledger


            ledger = Ledger(api_key=os.environ["LEDGER_API_KEY"])

            ledger.set_subscription_cancellation(customer_id="user_123",
            subscription_id=42, cancel_at_period_end=True)
        - lang: typescript
          label: TypeScript SDK (source only)
          source: >-
            import { Ledger } from "@ledger/sdk";


            const ledger = new Ledger({ apiKey: process.env.LEDGER_API_KEY ?? ""
            });

            await ledger.setSubscriptionCancellation({ subscriptionId: 42,
            customerId: "user_123", body: { cancelAtPeriodEnd: true } });
components:
  schemas:
    UpdateCustomerSubscriptionCancellationInput:
      type: object
      properties:
        cancelAtPeriodEnd:
          type: boolean
      required:
        - cancelAtPeriodEnd
      additionalProperties: false
    UpdateCustomerSubscriptionCancellationResponse:
      type: object
      properties:
        cancelAtPeriodEnd:
          type: boolean
        cancelsAt:
          type: string
          nullable: true
          format: date-time
      required:
        - cancelAtPeriodEnd
        - cancelsAt
    CustomerError:
      type: object
      properties:
        error:
          type: string
      required:
        - error
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer

````

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