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

# Pause a subscription's renewals

> Stops collecting renewals on an `active` subscription and returns the subscription. There is
no end date and no automatic resume: it stays paused until you resume it.

**Nothing is refunded or prorated.** The period the buyer has already paid for is untouched,
and an invoice that would fall inside the pause is voided rather than charged. On success the
subscription reads `paused`, `paused_at` is set, and `next_billing_at` is `null` because
nothing is scheduled to bill.

Refused with 422 `subscription_not_eligible` when the subscription is already paused
(`already_paused`), is not `active` (`not_active` — one that is `overdue` after a failed
payment cannot be paused), has a refund or a chargeback recorded against its payments
(`subscription_payment_not_updateable`), has no subscription at the payment provider
(`missing_processor_subscription`), or has another change still processing
(`change_in_flight`). A pause inside the 60 minutes before
the renewal is refused with 422 `too_close_to_renewal`, because the cycle it would stop may
already be billing, and one with no renewal date known with `renewal_date_unknown`.

The body is optional and carries one member: `reason`, your own note, recorded on the attempt. Text longer than 500 characters is truncated.

Requires the `subscriptions` permission at `write`. An API key holds a permission at the lower of its own level (`read` for a read-only key) and its holder's role; a key without it is refused with 403.



## OpenAPI

````yaml /api-reference/commerce-v1.openapi.json post /v1/commerce/subscriptions/{id}/pause
openapi: 3.0.3
info:
  description: >-
    Public REST API for COPE vendor integrations. Authenticate with a COPE API
    key and call the endpoints described below.
  title: COPE Public API
  version: v1
servers:
  - description: Production
    url: https://api.cope.com
security:
  - cope_sk: []
paths:
  /v1/commerce/subscriptions/{id}/pause:
    post:
      tags:
        - Subscriptions
      summary: Pause a subscription's renewals
      description: >-
        Stops collecting renewals on an `active` subscription and returns the
        subscription. There is

        no end date and no automatic resume: it stays paused until you resume
        it.


        **Nothing is refunded or prorated.** The period the buyer has already
        paid for is untouched,

        and an invoice that would fall inside the pause is voided rather than
        charged. On success the

        subscription reads `paused`, `paused_at` is set, and `next_billing_at`
        is `null` because

        nothing is scheduled to bill.


        Refused with 422 `subscription_not_eligible` when the subscription is
        already paused

        (`already_paused`), is not `active` (`not_active` — one that is
        `overdue` after a failed

        payment cannot be paused), has a refund or a chargeback recorded against
        its payments

        (`subscription_payment_not_updateable`), has no subscription at the
        payment provider

        (`missing_processor_subscription`), or has another change still
        processing

        (`change_in_flight`). A pause inside the 60 minutes before

        the renewal is refused with 422 `too_close_to_renewal`, because the
        cycle it would stop may

        already be billing, and one with no renewal date known with
        `renewal_date_unknown`.


        The body is optional and carries one member: `reason`, your own note,
        recorded on the attempt. Text longer than 500 characters is truncated.


        Requires the `subscriptions` permission at `write`. An API key holds a
        permission at the lower of its own level (`read` for a read-only key)
        and its holder's role; a key without it is refused with 403.
      operationId: commerce.subscriptions.pause
      parameters:
        - description: id public identifier.
          example: ps_A1b2C3d4E5f6
          in: path
          name: id
          required: true
          schema:
            example: ps_A1b2C3d4E5f6
            pattern: ^ps_[A-Za-z0-9]{8,32}$
            type: string
        - description: >-
            Required. At most 255 characters of valid UTF-8 with no NUL byte.
            The change attempt is recorded against this key for this
            subscription, and a retry that carries the same key and the same
            body does not change the subscription twice: it returns the
            subscription as it stands now. The exception is an attempt that
            failed at the payment provider or stopped responding: it is
            re-checked and then re-attempted. COPE also re-attempts, on its own,
            an attempt the payment provider did not confirm or that stopped
            responding, under the same re-check: usually within minutes, for up
            to 24 hours after it was recorded. The re-check asks whether
            subscription changes through the API are still enabled for the
            business and whether another change is still processing
            (`change_in_flight`: repeat under the same key once it settles); a
            price or plan change is also refused as `not_active` (final) once
            the subscription has ended and as `superseded` (final) when another
            price or plan change has been applied since it was recorded, and a
            pause, resume or cancel when the subscription has left the status it
            needs. A refusal of the first request under a key,
            `change_in_flight` included, is recorded against that key: once it
            settles, send the request again under a new key. The same key with a
            different body is refused with 409 idempotency_conflict.
          in: header
          name: Idempotency-Key
          required: true
          schema:
            maxLength: 255
            type: string
      requestBody:
        content:
          application/json:
            examples:
              with_reason:
                summary: Pause, with a note kept on the attempt
                value:
                  reason: Buyer asked for a two-month break
            schema:
              additionalProperties: false
              properties:
                reason:
                  description: >-
                    Optional. Recorded with the change for COPE's records; this
                    API does not return it. Longer text is truncated to 500
                    characters.
                  maxLength: 500
                  type: string
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  data:
                    additionalProperties: false
                    properties:
                      amount_cents:
                        deprecated: true
                        description: >-
                          The same value as `amount_minor_units`, under the name
                          this object first published. Use `amount_minor_units`;
                          `GET /v1/commerce/subscriptions` does not return this
                          field.
                        type: integer
                      amount_minor_units:
                        description: >-
                          The recurring amount in force, tax included, in the
                          minor units of `currency`. It is the same at every
                          renewal for the life of the subscription, including
                          one sold at a net price, until a price or plan change
                          replaces it. The tax is calculated again from this
                          amount at each charge, so a renewal's
                          `net_amount_minor_units` and `tax_minor_units` can
                          differ slightly from the purchase's while the total
                          stays the same.
                        type: integer
                      business:
                        additionalProperties: false
                        description: The business that sold the subscription.
                        properties:
                          id:
                            example: biz_A1b2C3d4E5f6G7h8
                            pattern: ^biz_[A-Za-z0-9_-]{8,32}$
                            type: string
                          object:
                            enum:
                              - business
                            type: string
                        required:
                          - object
                          - id
                        type: object
                      cancel_at:
                        description: >-
                          When the cancellation takes effect, or took effect.
                          `null` when none was scheduled, and when it is not
                          recorded.
                        format: date-time
                        nullable: true
                        type: string
                      cancelled_at:
                        description: >-
                          When the cancellation was accepted, or when the
                          subscription ended for an ending nobody asked for.
                          `null` when not cancelled, and when it is not
                          recorded.
                        format: date-time
                        nullable: true
                        type: string
                      created_at:
                        format: date-time
                        type: string
                      currency:
                        type: string
                      has_net_price:
                        description: >-
                          The basis these terms were set in: `true` when the
                          recurring amount was stated net of tax, `false` when
                          it was stated with the tax included. A price change
                          that leaves out `has_net_price` uses this basis.
                        type: boolean
                      id:
                        example: ps_A1b2C3d4E5f6
                        pattern: ^ps_[A-Za-z0-9]{8,32}$
                        type: string
                      line_item:
                        additionalProperties: false
                        description: The order line it was sold on.
                        properties:
                          id:
                            example: li_A1b2C3d4E5f6
                            pattern: ^li_[A-Za-z0-9]{8,32}$
                            type: string
                          object:
                            enum:
                              - line_item
                            type: string
                        required:
                          - object
                          - id
                        type: object
                      net_amount_minor_units:
                        description: >-
                          The part of `amount_minor_units` before tax, in the
                          minor units of `currency`.
                        type: integer
                      next_billing_at:
                        description: >-
                          The next renewal. `null` while paused, once a
                          cancellation has started, and while no renewal date is
                          known. A card renewal is charged at `next_billing_at`,
                          as soon as COPE finalises the renewal. A PayPal
                          renewal is charged by a run COPE makes every hour, so
                          within the hour after `next_billing_at`. A declined
                          renewal is retried about 1, 4 and 11 days after its
                          first attempt, on either payment method.
                        format: date-time
                        nullable: true
                        type: string
                      object:
                        enum:
                          - subscription
                        type: string
                      order:
                        additionalProperties: false
                        description: >-
                          The order it was sold in: `GET
                          /v1/commerce/orders/{id}`.
                        properties:
                          id:
                            example: ord_A1b2C3d4E5f6
                            pattern: ^ord_[A-Za-z0-9]{8,32}$
                            type: string
                          object:
                            enum:
                              - order
                            type: string
                        required:
                          - object
                          - id
                        type: object
                      paused_at:
                        description: '`null` unless `paused`.'
                        format: date-time
                        nullable: true
                        type: string
                      pending_change:
                        additionalProperties: false
                        description: >-
                          A price or plan change waiting for the next renewal:
                          present until a renewal bills its terms, on every
                          payment method. `null` when none is waiting and once a
                          cancellation has started. A renewal that bills nothing
                          (a 100% discount) does not count, so the change stays
                          pending until a paid renewal bills it.
                        nullable: true
                        properties:
                          amount_cents:
                            deprecated: true
                            description: The same value as `amount_minor_units`.
                            type: integer
                          amount_minor_units:
                            description: What the next renewal bills, tax included.
                            type: integer
                          effective_at:
                            description: >-
                              The next renewal, which is when it takes effect.
                              `null` while paused.
                            format: date-time
                            nullable: true
                            type: string
                          has_net_price:
                            description: >-
                              The basis these terms were set in: `true` when the
                              recurring amount was stated net of tax, `false`
                              when it was stated with the tax included. A price
                              change that leaves out `has_net_price` uses this
                              basis.
                            type: boolean
                          net_amount_minor_units:
                            description: >-
                              The part of `amount_minor_units` before tax, in
                              the minor units of `currency`.
                            type: integer
                          plan:
                            additionalProperties: false
                            properties:
                              id:
                                description: >-
                                  The id of the plan these terms were sold on or
                                  switched to. `null` when no recorded fact
                                  names the plan — for example, a subscription
                                  sold through an offer, a plan since deleted
                                  from the product, or one sold before plans
                                  were recorded.
                                example: plan_A1b2C3d4
                                nullable: true
                                pattern: ^plan_[A-Za-z0-9]{8,32}$
                                type: string
                              interval:
                                type: string
                              interval_count:
                                type: integer
                              name:
                                nullable: true
                                type: string
                              object:
                                enum:
                                  - payment_plan
                                type: string
                            required:
                              - object
                              - id
                              - name
                              - interval
                              - interval_count
                            type: object
                          tax_minor_units:
                            description: >-
                              The tax in `amount_minor_units`, at the rate the
                              subscription was sold at. Each renewal's tax is
                              calculated again when it is charged, from
                              `amount_minor_units`.
                            type: integer
                          type:
                            enum:
                              - price
                              - plan
                            type: string
                        required:
                          - type
                          - amount_cents
                          - amount_minor_units
                          - net_amount_minor_units
                          - tax_minor_units
                          - has_net_price
                          - plan
                          - effective_at
                        type: object
                      plan:
                        additionalProperties: false
                        description: >-
                          The plan in force for the period already billed.
                          Editing a product's payment plan (its interval, its
                          amounts or `second_payment_in`) never changes a
                          subscription already sold: each purchase keeps the
                          terms it was sold on, only later purchases use the
                          edit, and no subscription event is sent. To change a
                          sold subscription, use `POST
                          /v1/commerce/subscriptions/{id}/price` or `POST
                          /v1/commerce/subscriptions/{id}/plan`.
                        properties:
                          id:
                            description: >-
                              The id of the plan these terms were sold on or
                              switched to. `null` when no recorded fact names
                              the plan — for example, a subscription sold
                              through an offer, a plan since deleted from the
                              product, or one sold before plans were recorded.
                            example: plan_A1b2C3d4
                            nullable: true
                            pattern: ^plan_[A-Za-z0-9]{8,32}$
                            type: string
                          interval:
                            type: string
                          interval_count:
                            type: integer
                          name:
                            nullable: true
                            type: string
                          object:
                            enum:
                              - payment_plan
                            type: string
                        required:
                          - object
                          - id
                          - name
                          - interval
                          - interval_count
                        type: object
                      status:
                        description: >-
                          `canceling` means a cancellation was accepted and has
                          not taken effect; it becomes `cancelled` when the
                          subscription ends.
                        enum:
                          - pending
                          - trial
                          - active
                          - overdue
                          - paused
                          - canceling
                          - cancelled
                        type: string
                      tax_minor_units:
                        description: >-
                          The tax in `amount_minor_units`, at the rate the
                          subscription was sold at. Each renewal's tax is
                          calculated again when it is charged, from
                          `amount_minor_units`.
                        type: integer
                      updated_at:
                        description: >-
                          When the subscription last changed, in UTC to the
                          millisecond. It moves whenever another field of this
                          object changes, and can also move when none visibly
                          did, for example after a change attempt that was
                          refused. A change can become visible with an
                          `updated_at` slightly earlier than the moment you read
                          it (by up to the time a write takes to commit), and
                          changes can share one value, so sync with `GET
                          /v1/commerce/subscriptions`, which serves only changes
                          old enough to have committed and pages through equal
                          values, rather than by filtering on the last value you
                          saw.
                        format: date-time
                        type: string
                    required:
                      - id
                      - object
                      - status
                      - business
                      - order
                      - line_item
                      - plan
                      - amount_cents
                      - amount_minor_units
                      - net_amount_minor_units
                      - tax_minor_units
                      - has_net_price
                      - currency
                      - next_billing_at
                      - paused_at
                      - cancel_at
                      - cancelled_at
                      - created_at
                      - updated_at
                      - pending_change
                    type: object
                required:
                  - data
                type: object
          description: Successful response
        '400':
          content:
            application/problem+json:
              examples:
                subscription_idempotency_key_required:
                  summary: Missing Idempotency-Key header
                  value:
                    code: idempotency_key_required
                    detail: >-
                      an Idempotency-Key header is required for a subscription
                      change
                    errors:
                      - code: idempotency_key_required
                        detail: >-
                          an Idempotency-Key header is required for a
                          subscription change
                        param: idempotency_key
                    request_id: 0b6e3f2a-8c4d-4f1e-9a7b-5d2c8e1f4a90
                    status: 400
                    title: Idempotency Key Required
                    type: https://docs.cope.com/errors/idempotency_key_required
                subscription_invalid_idempotency_key:
                  summary: Malformed Idempotency-Key header
                  value:
                    code: invalid_idempotency_key
                    detail: >-
                      Idempotency-Key header must be at most 255 characters of
                      valid UTF-8 without a NUL byte
                    errors:
                      - code: invalid_idempotency_key
                        detail: >-
                          Idempotency-Key header must be at most 255 characters
                          of valid UTF-8 without a NUL byte
                        param: idempotency_key
                    request_id: 0b6e3f2a-8c4d-4f1e-9a7b-5d2c8e1f4a90
                    status: 400
                    title: Invalid Idempotency Key
                    type: https://docs.cope.com/errors/invalid_idempotency_key
                unparsable_request:
                  summary: Unparsable request
                  value:
                    code: invalid_request
                    detail: >-
                      The request could not be parsed. Check the query string
                      and the request body.
                    request_id: 0b6e3f2a-8c4d-4f1e-9a7b-5d2c8e1f4a90
                    status: 400
                    title: Invalid Request
                    type: https://docs.cope.com/errors/invalid_request
              schema:
                $ref: '#/components/schemas/PublicProblemDetail'
          description: Invalid request
        '401':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/PublicProblemDetail'
          description: Missing or invalid bearer token
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/PublicProblemDetail'
          description: Bearer token is not authorized for this route
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/PublicProblemDetail'
          description: Resource not found
        '409':
          content:
            application/problem+json:
              examples:
                subscription_idempotency_conflict:
                  summary: Idempotency key reused with a different body
                  value:
                    code: idempotency_conflict
                    detail: >-
                      request body does not match the original request for this
                      idempotency key
                    errors:
                      - code: idempotency_body_mismatch
                        detail: >-
                          request body does not match the original request for
                          this idempotency key
                        param: idempotency_key
                    request_id: 0b6e3f2a-8c4d-4f1e-9a7b-5d2c8e1f4a90
                    status: 409
                    title: Idempotency Conflict
                    type: https://docs.cope.com/errors/idempotency_conflict
              schema:
                $ref: '#/components/schemas/PublicProblemDetail'
          description: >-
            The idempotency key was already used for this subscription with a
            different body.
        '422':
          content:
            application/problem+json:
              examples:
                subscription_status_validation_failed:
                  summary: The body carries an unsupported member
                  value:
                    code: validation_failed
                    detail: resumes_at is not supported by this public endpoint
                    errors:
                      - code: unsupported
                        detail: resumes_at is not supported by this public endpoint
                        param: resumes_at
                    request_id: 0b6e3f2a-8c4d-4f1e-9a7b-5d2c8e1f4a90
                    status: 422
                    title: Validation Failed
                    type: https://docs.cope.com/errors/validation_failed
                too_close_to_renewal:
                  summary: The next renewal is inside the change cutoff
                  value:
                    code: too_close_to_renewal
                    detail: too close to renewal
                    errors:
                      - code: too_close_to_renewal
                        detail: too close to renewal
                        param: subscription_id
                    request_id: 0b6e3f2a-8c4d-4f1e-9a7b-5d2c8e1f4a90
                    status: 422
                    title: Too Close To Renewal
                    type: https://docs.cope.com/errors/too_close_to_renewal
                subscription_not_eligible:
                  summary: The subscription cannot be changed
                  value:
                    code: subscription_not_eligible
                    detail: non stripe rail
                    errors:
                      - code: non_stripe_rail
                        detail: non stripe rail
                        param: subscription_id
                    request_id: 0b6e3f2a-8c4d-4f1e-9a7b-5d2c8e1f4a90
                    status: 422
                    title: Subscription Not Eligible
                    type: https://docs.cope.com/errors/subscription_not_eligible
                subscription_already_paused:
                  summary: The subscription is already paused
                  value:
                    code: subscription_not_eligible
                    detail: already paused
                    errors:
                      - code: already_paused
                        detail: already paused
                        param: subscription_id
                    request_id: 0b6e3f2a-8c4d-4f1e-9a7b-5d2c8e1f4a90
                    status: 422
                    title: Subscription Not Eligible
                    type: https://docs.cope.com/errors/subscription_not_eligible
                subscription_not_active:
                  summary: Only an active subscription can be paused
                  value:
                    code: subscription_not_eligible
                    detail: not active
                    errors:
                      - code: not_active
                        detail: not active
                        param: subscription_id
                    request_id: 0b6e3f2a-8c4d-4f1e-9a7b-5d2c8e1f4a90
                    status: 422
                    title: Subscription Not Eligible
                    type: https://docs.cope.com/errors/subscription_not_eligible
              schema:
                $ref: '#/components/schemas/PublicProblemDetail'
          description: The body is invalid, or the subscription cannot be changed now
        '502':
          content:
            application/problem+json:
              examples:
                subscription_payment_provider_unconfirmed:
                  summary: The payment provider did not confirm the change
                  value:
                    code: payment_provider_unconfirmed
                    detail: >-
                      The payment provider did not confirm this change. It is
                      recorded, and COPE keeps completing or refusing it on its
                      own, usually within minutes, for up to 24 hours. Repeat
                      the request under the same Idempotency-Key to ask again
                      now; a price or plan change also shows its outcome in GET
                      …/changes.
                    errors:
                      - code: payment_provider_unconfirmed
                        detail: >-
                          The payment provider did not confirm this change. It
                          is recorded, and COPE keeps completing or refusing it
                          on its own, usually within minutes, for up to 24
                          hours. Repeat the request under the same
                          Idempotency-Key to ask again now; a price or plan
                          change also shows its outcome in GET …/changes.
                        param: subscription_id
                    request_id: 0b6e3f2a-8c4d-4f1e-9a7b-5d2c8e1f4a90
                    status: 502
                    title: Payment Provider Unconfirmed
                    type: https://docs.cope.com/errors/payment_provider_unconfirmed
              schema:
                $ref: '#/components/schemas/PublicProblemDetail'
          description: >-
            The payment provider did not confirm this change, and may already
            hold it. COPE keeps completing or refusing it on its own for up to
            24 hours. To act now, repeat the request under the same
            Idempotency-Key, never a new one: COPE retries the same change, and
            the answer may be success, a refusal such as `superseded` or
            `change_in_flight`, or 502 again. `detail` is fixed text and never
            repeats what the provider said.
        '503':
          content:
            application/problem+json:
              examples:
                user_not_ready:
                  summary: The key's user is not available yet
                  value:
                    code: user_not_ready
                    detail: Retry after 2 seconds
                    errors:
                      - code: user_not_ready
                        detail: Retry after 2 seconds
                    request_id: 0b6e3f2a-8c4d-4f1e-9a7b-5d2c8e1f4a90
                    status: 503
                    title: User Not Ready
                    type: https://docs.cope.com/errors/user_not_ready
                tenant_not_ready:
                  summary: The key's business is not available yet
                  value:
                    code: tenant_not_ready
                    detail: Retry after 2 seconds
                    errors:
                      - code: tenant_not_ready
                        detail: Retry after 2 seconds
                    request_id: 0b6e3f2a-8c4d-4f1e-9a7b-5d2c8e1f4a90
                    status: 503
                    title: Tenant Not Ready
                    type: https://docs.cope.com/errors/tenant_not_ready
              schema:
                $ref: '#/components/schemas/PublicProblemDetail'
          description: >-
            The API key is valid but its user or business is not available to
            this API yet (`user_not_ready`, `tenant_not_ready`). Retry after the
            `Retry-After` seconds.
        '504':
          content:
            application/problem+json:
              examples:
                gateway_timeout:
                  summary: The request did not complete in time
                  value:
                    code: gateway_timeout
                    detail: The request did not complete in time
                    errors:
                      - code: gateway_timeout
                        detail: The request did not complete in time
                    request_id: 0b6e3f2a-8c4d-4f1e-9a7b-5d2c8e1f4a90
                    status: 504
                    title: Gateway Timeout
                    type: https://docs.cope.com/errors/gateway_timeout
              schema:
                $ref: '#/components/schemas/PublicProblemDetail'
          description: >-
            The request did not complete in time, so its outcome is unknown and
            the change may have been applied. Repeat it under the same
            Idempotency-Key, never a new one: a new key asks for a second
            change.
      security:
        - cope_sk: []
components:
  schemas:
    PublicProblemDetail:
      additionalProperties: false
      properties:
        code:
          type: string
        detail:
          nullable: true
          type: string
        errors:
          items:
            additionalProperties: false
            properties:
              code:
                type: string
              detail:
                type: string
              param:
                type: string
            required:
              - code
              - detail
            type: object
          type: array
        request_id:
          description: >-
            Correlates this response with COPE's logs; the response also carries
            it as `X-Request-Id`. It is the `X-Request-Id` you sent when that is
            1-128 letters, digits, `_`, `@` or `-`, and otherwise one COPE
            generated. Quote it when you contact support.
          type: string
        status:
          type: integer
        title:
          type: string
        type:
          type: string
      required:
        - type
        - title
        - status
        - code
        - request_id
      type: object
  securitySchemes:
    cope_sk:
      description: >-
        Bearer credential for the public API: a live COPE API key (`ck_live_*`;
        keys issued earlier as `cope_sk_live_*` keep working). Dashboard sign-in
        tokens are not accepted.
      scheme: bearer
      type: http

````

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