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

# Update Subscription

> Partially updates an existing subscription. Immediate cancels, pauses and resumes are not accepted on this endpoint — use [`DELETE /subscriptions/{provider_subscription_id}`](./cancel-subscription.md) (cancel), [`POST /subscriptions/{provider_subscription_id}/pauses`](./pause-subscription.md) (pause), or [`DELETE /subscriptions/{provider_subscription_id}/pauses`](./resume-subscription.md) (resume) instead. To move or remove a cancel that is already scheduled, send `cancel_at`. Returns the updated subscription in the same shape as `GET /subscriptions/{provider_subscription_id}`.

Updates are never prorated: an item or price change creates no credit for unused time and no prorated charge. Within the same billing interval, the new price applies from the next renewal.

When an item change moves the subscription to a different billing interval, longer or shorter (for example monthly to every 3 months, or back), a new period starts at the change and the new price is charged in full immediately, with no credit for time already paid. Discounts already on the subscription apply to that charge, and a `once` discount sent in the same request lands on it. A trialing subscription, or a request that sets `trial_end`, starts no new period, so the change does not end the trial. An interval change on a paused subscription is a `400`; resume it first.

After a change, a subscription can hold at most one item, because every subscription item is a recurring price. Create a separate subscription for each recurring product.

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



## OpenAPI

````yaml /openapi.json put /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}:
    put:
      tags:
        - Subscriptions
      summary: Update Subscription
      description: >-
        Partially updates an existing subscription. Immediate cancels, pauses
        and resumes are not accepted on this endpoint — use [`DELETE
        /subscriptions/{provider_subscription_id}`](./cancel-subscription.md)
        (cancel), [`POST
        /subscriptions/{provider_subscription_id}/pauses`](./pause-subscription.md)
        (pause), or [`DELETE
        /subscriptions/{provider_subscription_id}/pauses`](./resume-subscription.md)
        (resume) instead. To move or remove a cancel that is already scheduled,
        send `cancel_at`. Returns the updated subscription in the same shape as
        `GET /subscriptions/{provider_subscription_id}`.


        Updates are never prorated: an item or price change creates no credit
        for unused time and no prorated charge. Within the same billing
        interval, the new price applies from the next renewal.


        When an item change moves the subscription to a different billing
        interval, longer or shorter (for example monthly to every 3 months, or
        back), a new period starts at the change and the new price is charged in
        full immediately, with no credit for time already paid. Discounts
        already on the subscription apply to that charge, and a `once` discount
        sent in the same request lands on it. A trialing subscription, or a
        request that sets `trial_end`, starts no new period, so the change does
        not end the trial. An interval change on a paused subscription is a
        `400`; resume it first.


        After a change, a subscription can hold at most one item, because every
        subscription item is a recurring price. Create a separate subscription
        for each recurring product.


        `/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: true
        content:
          application/json:
            schema:
              type: object
              properties:
                discounts:
                  type: array
                  items:
                    type: object
                    properties:
                      coupon:
                        type: string
                        description: >-
                          Provider coupon id. Exactly one of `coupon`,
                          `promotion_code` or `discount` per entry.
                      promotion_code:
                        type: string
                        description: >-
                          Provider promotion-code id. Exactly one of `coupon`,
                          `promotion_code` or `discount` per entry.
                      discount:
                        type: string
                        description: >-
                          Provider id of an **existing** discount (`di_...`) on
                          this subscription or its billing customer, to reuse it
                          rather than create a new one. Exactly one of `coupon`,
                          `promotion_code` or `discount` per entry.
                  description: >-
                    Replaces the subscription-level discounts with the ones you
                    send. **An empty array removes all of them.** Discounts on
                    individual items are not affected; use `items[].discounts`
                    for those. To keep a discount while changing the others,
                    resend it as `{ "discount": "<its provider_discount_id>" }`.
                    Each entry must specify **exactly one** of `coupon`,
                    `promotion_code` or `discount`. A blank or non-string member
                    is ignored rather than rejected, so `{"coupon": "",
                    "promotion_code": "test_promotion_code_id"}` is accepted as
                    a promotion-code discount. Ids are trimmed before use.
                    **Changed:** an empty array used to change nothing; it now
                    removes every subscription-level discount, so omit the field
                    to leave the discounts alone.
                default_payment_method:
                  type: string
                  description: Provider payment-method id (e.g. `pm_...`). Non-empty.
                items:
                  type: array
                  items:
                    type: object
                    properties:
                      provider_item_id:
                        type: string
                        description: >-
                          Existing provider subscription-item id to update or
                          remove.
                      provider_price_id:
                        type: string
                        description: Provider price id to add a new item.
                      quantity:
                        type: number
                        description: Item quantity.
                      deleted:
                        type: boolean
                        description: Set with `id` to remove the item.
                      discounts:
                        type: array
                        items:
                          type: object
                          properties:
                            coupon:
                              type: string
                              description: >-
                                Provider coupon id. Exactly one of `coupon`,
                                `promotion_code` or `discount` per entry.
                            promotion_code:
                              type: string
                              description: >-
                                Provider promotion-code id. Exactly one of
                                `coupon`, `promotion_code` or `discount` per
                                entry.
                            discount:
                              type: string
                              description: >-
                                Provider id of an **existing** discount
                                (`di_...`) on this subscription or its billing
                                customer, to reuse it rather than create a new
                                one. Exactly one of `coupon`, `promotion_code`
                                or `discount` per entry.
                        description: >-
                          Replaces **this item's** discounts with the ones you
                          send; an empty array removes them. Same entry shape as
                          the top-level `discounts`. Omit it to leave the item's
                          discounts unchanged. Only the item named by
                          `provider_item_id` is affected: other items and the
                          subscription-level discounts keep theirs. A new item
                          added with `provider_price_id` is created with these
                          discounts. On an item removed with `deleted: true`
                          they are accepted and ignored.
                  description: >-
                    Non-empty. Each entry needs at least one of
                    `provider_item_id` or `provider_price_id`; optional
                    `quantity` (non-negative integer), `deleted` (boolean, used
                    with `provider_item_id` to remove the item) and `discounts`
                    (this item's discounts). After the change the subscription
                    may hold at most one item: the count is the current items,
                    minus entries with `provider_item_id` and `deleted: true`,
                    plus entries without `provider_item_id` and without
                    `deleted: true`. `quantity: 0` does not remove an item.
                    Checked only when `items` is sent, so a subscription that
                    already holds several items can still change its other
                    fields.
                metadata:
                  type: object
                  additionalProperties:
                    type: string
                  description: >-
                    Free-form string key/value pairs. Merged, not replaced —
                    keys you omit are preserved; send a key with an empty-string
                    value to unset just that key. An empty `{}` clears nothing
                    and does not count as an update, so `metadata: {}` on its
                    own is a `400`.
                trial_end:
                  type: integer
                  description: >-
                    Unix timestamp in **seconds**; must be an integer in the
                    future. Starts a trial ending at that instant and moves the
                    subscription's billing anchor to it, so the next charge
                    lands on that date instead of the original schedule — the
                    way to push out a renewal when, say, a shipment was delayed.
                    Valid on its own. Three consequences to know before calling
                    it: **(1)** nothing is charged, though the provider does
                    record a **$0 invoice** with a single “Trial period” line
                    that will appear in `GET
                    /subscriptions/{provider_subscription_id}/invoices`. **(2)**
                    The subscription reports `status: "trialing"` until the date
                    passes, so `GET /subscriptions?status=active` will not
                    return it during that window — query `status=trialing` or
                    `status=all`. **(3)** The anchor move is **permanent**:
                    every later cycle bills on the new date, the original
                    schedule does not resume. Combining it with `items` or
                    `discounts` is allowed.
                cancel_at:
                  type:
                    - string
                    - integer
                    - 'null'
                  description: >-
                    Moves or removes a scheduled cancel. A **future** unix
                    timestamp in integer seconds, no later than the end of the
                    current billing period, cancels at that instant
                    (`cancel_at_period_end: false`); `"period_end"` cancels at
                    the end of the current period (`cancel_at_period_end:
                    true`); `null` removes any scheduled cancel, and is safe to
                    send when nothing is scheduled. `null` counts as an update.
                    Moving or removing a cancel creates no invoice and charges
                    nothing. A timestamp after the current billing period ends
                    is a `400`: a cancel date in a later period would renew the
                    subscription into a partial final period, which the payment
                    provider always bills prorated. A date exactly at the period
                    end is accepted and bills like `"period_end"`, but reports
                    `cancel_at_period_end: false`. A timestamp sent to a
                    subscription with no upcoming renewal is a `400`. When the
                    same request changes the billing interval, a timestamp is
                    checked against the end of the new period. A timestamp
                    cannot be combined with `trial_end` (send `trial_end` first,
                    then `cancel_at` in a separate request); `"period_end"` and
                    `null` can. `"now"` is a `400`: use `DELETE
                    /subscriptions/{provider_subscription_id}` to cancel
                    immediately. Needs the `payment-subscriptions:update`
                    permission, not `:cancel`.
            example:
              default_payment_method: test_payment_method_id
      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: active
                    description: null
                    items:
                      - provider_item_id: test_subscription_item_id
                        quantity: 2
                        metadata: null
                        price: null
                        product: null
                        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`; no
            updatable field provided; a discount entry carrying two or more of
            `coupon`, `promotion_code` and `discount`, or none of them
            (**changed:** an entry sending `discount` alongside `coupon` or
            `promotion_code` used to be accepted with `discount` ignored, and is
            now rejected); a `discounts` value, top-level or on an item, that is
            not an array or has an entry that is not an object; an items entry
            with neither an item id nor a price id; invalid
            `quantity`/`deleted`; an `items` change that would leave more than
            one item on the subscription (`A subscription can have only one
            recurring price. Create a separate subscription for each recurring
            product.`, checked before anything is changed); `proration_behavior`
            sent with any value other than `"none"` (`proration_behavior must be
            'none' or omitted: updates are never prorated`); `metadata` not an
            object, or any `metadata` value not a string; `trial_end` not an
            integer, or not in the future; `cancel_at` not `"period_end"`,
            `null` or an integer, or not in the future, or 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 sent as a timestamp to a subscription with no upcoming
            renewal, or as a timestamp together with `trial_end`; a `cancel_at`
            timestamp on a canceled or expired subscription (`Cannot change the
            cancel schedule of a terminal subscription`); an `items` change that
            moves a paused subscription to a different billing interval (`Resume
            the subscription before changing its billing interval`). An empty
            `metadata: {}` does not count as an updatable field, so on its own
            it yields “no updatable field provided”; the same holds for
            `proration_behavior: "none"` on its own. 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. Also an `items`
            entry whose `provider_price_id` the payment provider does not have
            (`items price not found: <id>`).
        '500':
          description: >-
            An upstream payment-provider error with no client-error status. The
            payment provider's own rejections keep its status instead: a `400`,
            or a `404` when the provider reports something missing (see the
            `404` response).
      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.