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

# Create Refund

> Issues a refund against a paid invoice, recorded on one credit note. The card part of `amount` goes back to the invoice's card payments; `balance_amount`, when sent, goes back to the billing customer's credit balance instead.

**Concurrency.** Two refunds for the same invoice sent at the same time under different keys are not serialized: each checks the caps before the other writes, so together they can exceed the `balance_amount` cap. The payment provider's own limit on the invoice total still bounds them.



## OpenAPI

````yaml /openapi.json post /invoices/{provider_invoice_id}/refunds
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/{provider_invoice_id}/refunds:
    post:
      tags:
        - Invoices
      summary: Create Refund
      description: >-
        Issues a refund against a paid invoice, recorded on one credit note. The
        card part of `amount` goes back to the invoice's card payments;
        `balance_amount`, when sent, goes back to the billing customer's credit
        balance instead.


        **Concurrency.** Two refunds for the same invoice sent at the same time
        under different keys are not serialized: each checks the caps before the
        other writes, so together they can exceed the `balance_amount` cap. The
        payment provider's own limit on the invoice total still bounds them.
      parameters:
        - in: path
          name: provider_invoice_id
          required: true
          schema:
            type: string
          description: Provider invoice id (e.g. `test_invoice_id`).
        - in: header
          name: Idempotency-Key
          required: false
          schema:
            type: string
          description: >-
            Deduplicates retried requests with the same key and parameters
            instead of creating a second resource (roughly a 24-hour replay
            window). Recommended: an opaque, randomly-generated value such as a
            UUID. A refund is created before the credit note that records it: if
            the call fails after a refund went through, retry with the **same**
            key — the payment provider replays that refund instead of creating a
            second one, and the retry links it on the credit note. That promise
            covers a failed credit note; retry a failed call within the 24-hour
            window, because after it the payment provider treats the retry as a
            new request and can refund again. On an invoice paid in more than
            one payment, if one payment's refund is rejected after another's
            went through, the retry replays the same rejection and the refund
            that went through stays unlinked: it is not counted against the
            refundable amount, so contact OpenLoop before retrying under a new
            key. A same-key retry of a call that already succeeded returns the
            original refund without refunding again — at any time with a key;
            the same key with a different `amount`, `balance_amount` or `reason`
            returns `400`. Without a key the scope is derived from `amount`,
            `balance_amount` and `reason`, and an identical keyless request is
            treated as a retry of the first for 24 hours after it succeeded;
            after that it is a new refund — send an `Idempotency-Key` to issue
            two equal refunds sooner.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: integer
                  description: >-
                    Total refund in cents, card and balance together. Positive
                    integer. Its card part (`amount − balance_amount`) is no
                    greater than the invoice's card-refundable amount: what its
                    paid card payments paid, minus the refunds already linked to
                    credit notes on the invoice. A payment recorded outside the
                    payment provider is not refundable to card.
                balance_amount:
                  type: integer
                  description: >-
                    Part of `amount`, in cents, returned to the billing
                    customer's balance instead of the card. Integer from `0` to
                    `amount`; absent means `0` (card only). No greater than the
                    credit that was applied to the invoice from the balance,
                    minus what earlier credit notes already returned to the
                    balance — so only the credit-paid part goes back to the
                    balance.
                reason:
                  type: string
                  description: >-
                    One of `duplicate`, `fraudulent`, `order_change`,
                    `product_unsatisfactory`.
                description:
                  type: string
                  description: >-
                    Free-text note; sent to the provider as the credit note
                    `memo`.
              required:
                - amount
                - reason
            example:
              amount: 19900
              balance_amount: 2000
              reason: duplicate
              description: Refunded duplicate charge
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      provider_credit_note_id:
                        type: string
                        description: Provider credit note id (e.g. `cn_123`).
                      provider_invoice_id:
                        type: string
                        description: Invoice the refund was issued against.
                      status:
                        type: string
                        description: Credit note status (`issued` or `void`).
                      amount:
                        type: number
                        description: Credit note amount in cents (card + balance).
                      refund_amount:
                        type: number
                        description: >-
                          Cents refunded to card (the sum of the refunds linked
                          on the credit note).
                      balance_amount:
                        type: number
                        description: >-
                          Cents returned to the billing customer's balance.
                          `refund_amount + balance_amount = amount`.
                      currency:
                        type: string
                        description: Currency code (e.g. `usd`).
                      reason:
                        type:
                          - string
                          - 'null'
                        description: Refund reason.
                      description:
                        type:
                          - string
                          - 'null'
                        description: Free-text note; echoes the request `description`.
                      credit_note_pdf:
                        type:
                          - string
                          - 'null'
                        description: URL to the credit note PDF.
                      created:
                        type: number
                        description: Unix timestamp of creation.
                required:
                  - data
              example:
                data:
                  provider_credit_note_id: test_credit_note_id
                  provider_invoice_id: test_invoice_id
                  status: issued
                  amount: 19900
                  refund_amount: 17900
                  balance_amount: 2000
                  currency: usd
                  reason: duplicate
                  description: Refunded duplicate charge
                  credit_note_pdf: https://pay.stripe.com/credit_notes/abc/pdf
                  created: 1900
        '400':
          description: >-
            ValidationError: Missing body; missing `provider_invoice_id`;
            missing/non-positive `amount`; the card part of `amount` above the
            invoice's card-refundable amount; `balance_amount` not an integer,
            negative or above `amount`; `balance_amount` above the credit
            applied to the invoice that can still be returned; missing/invalid
            `reason`; an `Idempotency-Key` whose derived refund key would exceed
            255 characters; an `Idempotency-Key` already used for a different
            refund on this invoice; `amount` above what can still be credited on
            the invoice (every earlier credit note counts, including ones issued
            outside this endpoint); the invoice is not `paid` (for example
            `open` or `uncollectible`). ProviderError: the payment provider
            rejected the refund, for example the payment was already refunded
            outside a credit note.
        '401':
          description: Missing or invalid bearer token.
        '403':
          description: >-
            No configuration exists for your account, or provider access has
            been disabled for it.
        '500':
          description: An upstream provider error with no client-error status.
      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.