> ## 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.

# Pause Subscription

> Pauses a subscription so it stops generating invoices and will not advance to new billing periods (resumable later via a separate resume endpoint). This does not change the subscription's `status` — check `paused` and `resumes_at` in the response instead. A subscription that has an attached schedule cannot be paused.



## OpenAPI

````yaml /openapi.json post /subscriptions/{provider_subscription_id}/pauses
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}/pauses:
    post:
      tags:
        - Subscriptions
      summary: Pause Subscription
      description: >-
        Pauses a subscription so it stops generating invoices and will not
        advance to new billing periods (resumable later via a separate resume
        endpoint). This does not change the subscription's `status` — check
        `paused` and `resumes_at` in the response instead. A subscription that
        has an attached schedule cannot be paused.
      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:
                cycles:
                  type:
                    - integer
                    - 'null'
                  description: >-
                    How many billing cycles to pause for. Positive integer, or
                    `null` for an open-ended pause (clears any previously
                    scheduled resume). Omit the field entirely, rather than
                    sending an empty body, to leave an existing scheduled resume
                    untouched.
            example:
              cycles: 2
      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: '`status` is `paused` after a successful pause.'
                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: paused
                    description: null
                    items:
                      - provider_item_id: test_subscription_item_id
                        quantity: 1
                        metadata: null
                        price:
                          provider_price_id: test_price_id
                          provider_product_id: test_product_id
                          currency: usd
                          amount_cents: 4999
                          active: true
                          billing_scheme: per_unit
                          created: 1000
                          recurring:
                            interval: month
                            interval_count: 1
                        product:
                          name: Care plan
                          description: null
                          metadata: {}
                        current_period_end: 1700
                        current_period_start: 1300
                        created: 1300
                        discounts: []
                    cancellation_details: null
                    discounts: []
                    cancel_at_period_end: false
                    cancel_at: null
                    canceled_at: null
                    ended_at: null
                    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`; the
            subscription has an attached schedule.
        '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 config not found.
        '500':
          description: An upstream provider error.
      security:
        - serviceToken: []
        - userToken: []
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.