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

# Cancel Subscription

> Cancels a subscription. Supports three cancellation timing modes selected by the request body's `cancel_at` field: immediate (`"now"`), at the end of the current billing period (`"period_end"`), or at a specific future timestamp (`<unix-seconds>`). The body is optional: without one, or without `cancel_at`, the subscription cancels at the end of the current billing period. Returns the resulting subscription in the same shape as [`GET /subscriptions/{provider_subscription_id}`](./get-subscription.md).

Cancellations are never prorated: no credit for unused time is created, whichever `cancel_at` you send.

`/v0.1` of this operation is deprecated and stops working on 2027-01-17.



## OpenAPI

````yaml /openapi.json delete /subscriptions/{provider_subscription_id}
openapi: 3.1.0
info:
  title: OpenLoop API
  version: 0.1.0
  description: >-
    Unified reference for the OpenLoop Patient (clinical) and Payments & Revenue
    APIs.
servers:
  - url: https://api.openloophealth.com/v0.1
    description: Production partner edge
  - url: https://api-staging.openloophealth.com/v0.1
    description: Staging partner edge (sandbox credentials)
security: []
paths:
  /subscriptions/{provider_subscription_id}:
    delete:
      tags:
        - Subscriptions
      summary: Cancel Subscription
      description: >-
        Cancels a subscription. Supports three cancellation timing modes
        selected by the request body's `cancel_at` field: immediate (`"now"`),
        at the end of the current billing period (`"period_end"`), or at a
        specific future timestamp (`<unix-seconds>`). The body is optional:
        without one, or without `cancel_at`, the subscription cancels at the end
        of the current billing period. Returns the resulting subscription in the
        same shape as [`GET
        /subscriptions/{provider_subscription_id}`](./get-subscription.md).


        Cancellations are never prorated: no credit for unused time is created,
        whichever `cancel_at` you send.


        `/v0.1` of this operation is deprecated and stops working on 2027-01-17.
      parameters:
        - in: path
          name: provider_subscription_id
          required: true
          schema:
            type: string
          description: Provider subscription ID (e.g. `test_subscription_id`).
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                cancel_at:
                  oneOf:
                    - type: string
                      enum:
                        - now
                        - period_end
                    - type: number
                    - type: 'null'
                  description: >-
                    `"now"` to cancel immediately, `"period_end"` to cancel at
                    the end of the current billing period, or a future Unix
                    timestamp (integer seconds), no later than the end of the
                    current billing period, to cancel at that time. Defaults to
                    `"period_end"` when omitted or `null`.
                cancellation_details:
                  type: object
                  properties:
                    comment:
                      type: string
                      description: Free-text cancellation comment.
                    feedback:
                      type: string
                      description: >-
                        One of `customer_service`, `low_quality`,
                        `missing_features`, `other`, `switched_service`,
                        `too_complex`, `too_expensive`, `unused`.
                  description: Optional.
            example:
              cancel_at: period_end
              cancellation_details:
                comment: Switching plans
                feedback: switched_service
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      config_id:
                        type: string
                        description: Configuration ID.
                      provider_account_id:
                        type:
                          - string
                          - 'null'
                        description: Provider account ID.
                      payment_provider:
                        type: string
                        description: Provider enum (e.g. `"stripe"`).
                      subscription:
                        type: object
                        properties:
                          provider_customer_id:
                            type: string
                            description: Provider customer ID owning the subscription.
                          provider_subscription_id:
                            type: string
                            description: Provider subscription ID.
                          status:
                            type: string
                            description: Provider subscription status.
                          description:
                            type:
                              - string
                              - 'null'
                            description: Subscription description.
                          items:
                            type: array
                            items:
                              type: object
                              properties:
                                provider_item_id:
                                  type: string
                                  description: Provider subscription-item ID.
                                quantity:
                                  type: number
                                  description: Item quantity.
                                metadata:
                                  type:
                                    - object
                                    - 'null'
                                  description: >-
                                    Custom metadata (string key/value pairs) or
                                    `null`.
                                price:
                                  type:
                                    - object
                                    - 'null'
                                  properties:
                                    provider_price_id:
                                      type: string
                                      description: Provider price ID.
                                    provider_product_id:
                                      type: string
                                      description: Provider product ID.
                                    currency:
                                      type: string
                                      description: ISO 4217 currency code.
                                    amount_cents:
                                      type: number
                                      description: Unit amount in cents.
                                    active:
                                      type:
                                        - boolean
                                        - 'null'
                                      description: Whether the price is currently active.
                                    billing_scheme:
                                      type:
                                        - string
                                        - 'null'
                                      description: >-
                                        Provider billing scheme (e.g.
                                        `"per_unit"`).
                                    created:
                                      type:
                                        - number
                                        - 'null'
                                      description: Unix timestamp the price was created.
                                    recurring:
                                      type:
                                        - object
                                        - 'null'
                                      properties:
                                        interval:
                                          type: string
                                          description: Billing interval (e.g. `"month"`).
                                        interval_count:
                                          type: number
                                          description: Number of intervals per billing cycle.
                                      description: >-
                                        Recurring interval details or `null` for
                                        one-time prices.
                                  description: Price details or `null`.
                                product:
                                  type:
                                    - object
                                    - 'null'
                                  properties:
                                    name:
                                      type: string
                                      description: Product name.
                                    description:
                                      type:
                                        - string
                                        - 'null'
                                      description: Product description.
                                    metadata:
                                      type: object
                                      description: >-
                                        Custom metadata (string key/value
                                        pairs).
                                  description: Product details or `null`.
                                current_period_start:
                                  type:
                                    - number
                                    - 'null'
                                  description: Unix timestamp of the current period start.
                                current_period_end:
                                  type:
                                    - number
                                    - 'null'
                                  description: Unix timestamp of the current period end.
                                created:
                                  type:
                                    - number
                                    - 'null'
                                  description: Unix timestamp the item was created.
                                discounts:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      provider_discount_id:
                                        type: string
                                        description: Provider discount ID.
                                      provider_coupon_id:
                                        type:
                                          - string
                                          - 'null'
                                        description: >-
                                          Provider coupon ID backing this
                                          discount, or `null`.
                                      provider_promotion_code_id:
                                        type:
                                          - string
                                          - 'null'
                                        description: >-
                                          Provider promotion code ID that created
                                          this discount, or `null` when a coupon
                                          was applied directly.
                                      start:
                                        type:
                                          - number
                                          - 'null'
                                        description: Unix timestamp the discount started.
                                      end:
                                        type:
                                          - number
                                          - 'null'
                                        description: >-
                                          Unix timestamp the discount ends, or
                                          `null` if open-ended.
                                  description: >-
                                    Discounts applied to this item only,
                                    separate from the subscription-level
                                    `discounts`. Empty array when none.
                            description: Subscription items.
                          cancellation_details:
                            type:
                              - object
                              - 'null'
                            properties:
                              comment:
                                type:
                                  - string
                                  - 'null'
                                description: Cancellation comment.
                              feedback:
                                type:
                                  - string
                                  - 'null'
                                description: Cancellation feedback code.
                              reason:
                                type:
                                  - string
                                  - 'null'
                                description: Cancellation reason.
                            description: Cancellation metadata or `null`.
                          discounts:
                            type: array
                            items:
                              type: object
                              properties:
                                provider_discount_id:
                                  type: string
                                  description: Provider discount ID.
                                provider_coupon_id:
                                  type:
                                    - string
                                    - 'null'
                                  description: >-
                                    Provider coupon ID backing this discount, or
                                    `null`.
                                provider_promotion_code_id:
                                  type:
                                    - string
                                    - 'null'
                                  description: >-
                                    Provider promotion code ID that created this
                                    discount, or `null` when a coupon was
                                    applied directly.
                                start:
                                  type:
                                    - number
                                    - 'null'
                                  description: Unix timestamp the discount started.
                                end:
                                  type:
                                    - number
                                    - 'null'
                                  description: >-
                                    Unix timestamp the discount ends, or `null`
                                    if open-ended.
                            description: >-
                              Discounts currently applied to the subscription.
                              Empty array when none.
                          cancel_at_period_end:
                            type: boolean
                            description: Whether the subscription cancels at period end.
                          cancel_at:
                            type:
                              - number
                              - 'null'
                            description: >-
                              Unix timestamp the subscription is scheduled to
                              cancel.
                          canceled_at:
                            type:
                              - number
                              - 'null'
                            description: Unix timestamp the subscription was canceled.
                          ended_at:
                            type:
                              - number
                              - 'null'
                            description: Unix timestamp the subscription ended.
                          paused:
                            type: boolean
                            description: Whether the subscription is currently paused.
                          resumes_at:
                            type:
                              - number
                              - 'null'
                            description: >-
                              Unix timestamp the subscription is scheduled to
                              resume, or `null`.
                          metadata:
                            type: object
                            additionalProperties:
                              type: string
                            description: >-
                              Free-form string key/value pairs attached to the
                              subscription.
                          start_date:
                            type: number
                            description: Unix timestamp the subscription started.
                          trial_start:
                            type:
                              - number
                              - 'null'
                            description: Unix timestamp the trial started.
                          trial_end:
                            type:
                              - number
                              - 'null'
                            description: Unix timestamp the trial ends/ended.
                          collection_method:
                            type: string
                            description: '`charge_automatically` or `send_invoice`.'
                          created:
                            type:
                              - number
                              - 'null'
                            description: Unix timestamp.
                          last_invoice:
                            type:
                              - object
                              - 'null'
                            properties:
                              provider_invoice_id:
                                type: string
                                description: Provider invoice ID.
                              created:
                                type:
                                  - number
                                  - 'null'
                                description: Unix timestamp the invoice was created.
                            description: Last invoice reference or `null`.
                          provider_payment_method_id:
                            type:
                              - string
                              - 'null'
                            description: >-
                              Payment-method id that paid the latest invoice.
                              When no payment method paid it (for example during
                              a trial, or when the invoice was settled from
                              credit balance), the payment method the payment
                              provider will charge next: the subscription's
                              default, otherwise the billing customer's invoice
                              default. `null` when none is set.
                          billing_cycle_anchor:
                            type: number
                            description: >-
                              Unix timestamp the subscription's billing cycles
                              are anchored to.
                        description: The subscription.
                required:
                  - data
              example:
                data:
                  config_id: test_config_id
                  provider_account_id: test_account_id
                  payment_provider: stripe
                  subscription:
                    provider_customer_id: test_customer_id
                    provider_subscription_id: test_subscription_id
                    status: canceled
                    description: null
                    items: []
                    cancellation_details:
                      comment: no longer needed
                      feedback: unused
                      reason: cancellation_requested
                    discounts: []
                    cancel_at_period_end: false
                    cancel_at: null
                    canceled_at: 2000
                    ended_at: 2000
                    paused: false
                    resumes_at: null
                    metadata: {}
                    start_date: 1300
                    trial_start: null
                    trial_end: null
                    collection_method: charge_automatically
                    created: 1300
                    last_invoice:
                      provider_invoice_id: test_invoice_id
                      created: 1300
                    provider_payment_method_id: test_payment_method_id
                    billing_cycle_anchor: 1300
        '400':
          description: >-
            ValidationError: Missing/empty `provider_subscription_id`;
            `cancel_at` not `"now"` / `"period_end"` / a future integer
            timestamp; a timestamp after the current billing period ends
            (`cancel_at must not be after the current billing period ends; use
            'period_end' to cancel at the end of the period`), or when the
            subscription has no upcoming renewal to read the period end from
            (`Cannot check cancel_at against the billing period: the
            subscription has no upcoming renewal`); `prorate` sent with any
            value other than `false` (`prorate must be false or omitted:
            cancellations are never prorated`); out-of-enum
            `cancellation_details.feedback`. ProviderError: the payment provider
            rejected the request, including its refusal of the billing-period
            lookup used to check a `cancel_at` timestamp.
        '401':
          description: Missing or invalid bearer token.
        '403':
          description: >-
            No configuration exists for your account, or provider access has
            been disabled for it.
        '404':
          description: >-
            NotFoundError: Subscription not found (the payment provider
            `resource_missing` or 404), or config not found.
        '500':
          description: An upstream provider error.
      security:
        - serviceToken: []
        - userToken: []
      servers:
        - url: https://api.openloophealth.com/v0.2
          description: Production partner edge
        - url: https://api-staging.openloophealth.com/v0.2
          description: Staging partner edge (sandbox credentials)
components:
  securitySchemes:
    serviceToken:
      type: oauth2
      description: >-
        Service (M2M) access token issued by POST /auth/token using the
        client_credentials grant. Required scopes, where known, are listed on
        each operation below.
      flows:
        clientCredentials:
          tokenUrl: https://api.openloophealth.com/v0.1/auth/token
          scopes: {}
    userToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        User access token issued by POST /auth/token via the verification-code
        grant (after Verify a one-time code) or the refresh_token grant.

````

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