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

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



## OpenAPI

````yaml /openapi.json get /invoices
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:
  /invoices:
    get:
      tags:
        - Invoices
      summary: Get Invoices
      description: >-
        Lists invoices 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 invoices to return. Default 10, max 100.
          example: '5'
        - in: query
          name: status
          required: false
          schema:
            type: string
          description: >-
            Filter by invoice status (`draft`, `open`, `paid`, `void`,
            `uncollectible`). Default `open`.
          example: paid
      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"`).
                      invoices:
                        type: array
                        items:
                          type: object
                          properties:
                            provider_customer_id:
                              type: string
                              description: Provider customer ID owning the invoice.
                            provider_invoice_id:
                              type:
                                - string
                                - 'null'
                              description: >-
                                Provider invoice ID. Always present on a created
                                invoice; `null` only on an invoice preview,
                                which has no id yet.
                            provider_subscription_id:
                              type:
                                - string
                                - 'null'
                              description: Subscription that generated the invoice, if any.
                            number:
                              type:
                                - string
                                - 'null'
                              description: Provider-assigned invoice number.
                            description:
                              type:
                                - string
                                - 'null'
                              description: Invoice description.
                            status:
                              type: string
                              description: >-
                                Invoice status (`draft`, `open`, `paid`, `void`,
                                `uncollectible`).
                            currency:
                              type: string
                              description: Currency code (e.g. `"usd"`).
                            paid_date:
                              type: number
                              description: >-
                                Unix timestamp the invoice was paid (`0` if
                                unpaid).
                            due_date:
                              type:
                                - number
                                - 'null'
                              description: Unix timestamp the invoice is due.
                            total_amount:
                              type: number
                              description: Invoice total in cents.
                            total_paid:
                              type: number
                              description: Amount paid in cents.
                            post_payment_credit_notes_amount:
                              type: number
                              description: >-
                                Total of all credit notes issued against the
                                invoice after it was paid, in cents. `0` when
                                none exist; above `0` means the invoice has been
                                at least partially refunded through a credit
                                note. Does not capture a refund issued directly
                                on the payment.
                            period_start:
                              type: number
                              description: Unix timestamp — billing period start.
                            period_end:
                              type: number
                              description: Unix timestamp — billing period end.
                            billing_reason:
                              type:
                                - string
                                - 'null'
                              description: >-
                                Why the invoice was created (e.g.
                                `subscription_cycle`).
                            collection_method:
                              type: string
                              description: '`charge_automatically` or `send_invoice`.'
                            hosted_invoice_url:
                              type:
                                - string
                                - 'null'
                              description: >-
                                the payment provider-hosted invoice page (view +
                                download PDF).
                            invoice_pdf:
                              type:
                                - string
                                - 'null'
                              description: Direct link to the invoice PDF.
                            metadata:
                              type: object
                              additionalProperties:
                                type: string
                              description: >-
                                Free-form string key/value pairs attached to the
                                invoice.
                            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 that created the
                                      discount, or `null`.
                                  provider_promotion_code_id:
                                    type:
                                      - string
                                      - 'null'
                                    description: >-
                                      Provider promotion code ID that created
                                      the discount, or `null` when a coupon was
                                      applied directly.
                              description: Each `{ provider_discount_id }`.
                            payments:
                              type: array
                              items:
                                type: object
                                properties:
                                  provider_payment_id:
                                    type: string
                                    description: Provider payment (invoice-payment) ID.
                                  provider_payment_intent_id:
                                    type:
                                      - string
                                      - 'null'
                                    description: >-
                                      Provider payment intent ID for this
                                      payment. `null` whenever the provider
                                      recorded no payment intent for it — a
                                      charge payment, a payment-record payment,
                                      or an invoice finalized before 2019-03-15.
                                  amount_paid_cents:
                                    type: number
                                    description: Amount paid in cents.
                                  amount_requested_cents:
                                    type: number
                                    description: Amount requested in cents.
                                  currency:
                                    type: string
                                    description: Currency code (e.g. `"usd"`).
                                  created:
                                    type: number
                                    description: Unix timestamp the payment was created.
                              description: >-
                                Each `{ provider_payment_id, amount_paid_cents,
                                amount_requested_cents, currency, created }`.
                            lines:
                              type: array
                              items:
                                type: object
                                properties:
                                  provider_product_id:
                                    type: string
                                    description: Provider product ID.
                                  provider_price_id:
                                    type: string
                                    description: Provider price ID.
                                  product:
                                    type:
                                      - object
                                      - 'null'
                                    properties:
                                      name:
                                        type:
                                          - string
                                          - 'null'
                                        description: Product name.
                                      description:
                                        type:
                                          - string
                                          - 'null'
                                        description: Product description.
                                      status:
                                        type: string
                                        description: Product status.
                                      metadata:
                                        type: object
                                        description: >-
                                          Custom metadata (string key/value
                                          pairs).
                                    description: Product details or `null`.
                                  billing_interval:
                                    type:
                                      - string
                                      - 'null'
                                    description: Billing interval (e.g. `"month"`).
                                  billing_interval_count:
                                    type:
                                      - number
                                      - 'null'
                                    description: Number of intervals per billing cycle.
                                  currency:
                                    type: string
                                    description: Currency code (e.g. `"usd"`).
                                  description:
                                    type:
                                      - string
                                      - 'null'
                                    description: Line description.
                                  amount_cents:
                                    type: number
                                    description: Line amount in cents.
                                  quantity:
                                    type: number
                                    description: Line quantity.
                                  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 that created the
                                            discount, or `null`.
                                        provider_promotion_code_id:
                                          type:
                                            - string
                                            - 'null'
                                          description: >-
                                            Provider promotion code ID that created
                                            the discount, or `null` when a coupon
                                            was applied directly.
                                    description: >-
                                      Discounts applied to the line item (same
                                      shape as the invoice `discounts` fields
                                      above).
                              description: >-
                                Line items (`provider_product_id`,
                                `provider_price_id`, `product`,
                                `billing_interval`, `billing_interval_count`,
                                `currency`, `description`, `amount_cents`,
                                `quantity`, `discounts`).
                            created:
                              type:
                                - number
                                - 'null'
                              description: Unix timestamp the invoice was created.
                        description: >-
                          Array of invoices, newest first by `created` within
                          each matching customer record at the payment provider.
                          When an email maps to several records the blocks are
                          concatenated newest record first, so the array is not
                          globally sorted.
                required:
                  - data
              example:
                data:
                  config_id: test_config_id
                  provider_account_id: test_account_id
                  payment_provider: stripe
                  invoices:
                    - provider_customer_id: test_customer_id
                      provider_invoice_id: test_invoice_id
                      provider_subscription_id: test_subscription_id_2
                      number: test_invoice_number
                      description: null
                      status: paid
                      currency: usd
                      paid_date: 1500
                      due_date: 1600
                      total_amount: 10000
                      total_paid: 10000
                      post_payment_credit_notes_amount: 0
                      period_start: 1100
                      period_end: 1300
                      billing_reason: subscription_cycle
                      collection_method: charge_automatically
                      hosted_invoice_url: https://invoice.stripe.com/i/test_invoice_id
                      invoice_pdf: https://invoice.stripe.com/i/test_invoice_id/pdf
                      discounts: []
                      payments:
                        - provider_payment_id: test_payment_id
                          provider_payment_intent_id: test_payment_intent_id
                          amount_paid_cents: 10000
                          amount_requested_cents: 10000
                          currency: usd
                          created: 1400
                      lines: []
                      created: 1000
        '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.