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

# Get Subscriptions

> Lists subscriptions for a customer identified by email. Supports limit and status filtering.



## OpenAPI

````yaml /openapi.json get /subscriptions
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:
    get:
      tags:
        - Subscriptions
      summary: Get Subscriptions
      description: >-
        Lists subscriptions for a customer identified by email. Supports limit
        and status filtering.
      parameters:
        - in: query
          name: email
          required: true
          schema:
            type: string
          description: >-
            Customer email; normalized to lowercase (and trimmed) server-side
            before the provider query.
          example: customer@example.com
        - in: query
          name: limit
          required: false
          schema:
            type: integer
          description: Maximum subscriptions to return. Default 10, max 100.
          example: '5'
        - in: query
          name: status
          required: false
          schema:
            type: string
          description: >-
            Filter by subscription status (`active`, `past_due`, `canceled`,
            `incomplete`, `incomplete_expired`, `paused`, `trialing`, `unpaid`,
            `all`). Default `active`.
          example: active
      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"`).
                      subscriptions:
                        type: array
                        items:
                          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: 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 (`provider_item_id`,
                                `quantity`, `metadata`, `price`, `product`,
                                `current_period_start`, `current_period_end`,
                                `created`).
                            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: '`{ comment, feedback, reason }`.'
                            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 the subscription was created.
                            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: '`{ provider_invoice_id, created }`.'
                            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: >-
                          Array of subscriptions. When an email maps to several
                          customer records at the payment provider, each
                          record's subscriptions are grouped together, newest
                          record first.
                required:
                  - data
              example:
                data:
                  config_id: test_config_id
                  provider_account_id: test_account_id
                  payment_provider: stripe
                  subscriptions:
                    - provider_customer_id: test_customer_id
                      provider_subscription_id: test_subscription_id_2
                      status: active
                      description: null
                      items: []
                      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: 1100
                      trial_start: null
                      trial_end: null
                      collection_method: charge_automatically
                      created: 1100
                      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 `email`; invalid `limit` or `status`.'
        '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: no billing customer has this email (`Customer not
            found`). The read answers 404, not an empty list.
        '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.