> ## 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 Balance Transaction

> Grants account credit to one of your billing customers, or claws unused credit back. `amount` uses the payment provider's sign, the same convention as the billing customer's `balance`: **a negative amount grants credit (at most `10000`, $100.00 in USD, per request), and a positive amount claws credit back (at most the remaining credit, so the balance never goes above `0`)**. The grant itself is not invoiced: the credit appears on the invoice it pays, and `description` / `metadata` record why it was granted. The part of an invoice paid with credit is refunded back to the balance, not to the card, with `balance_amount` on `POST /invoices/{provider_invoice_id}/refunds`. Concurrent clawbacks for the same customer are not serialized.

**Retrying a clawback.** The remaining-credit check runs against the live balance before the request reaches the payment provider, so retrying a clawback that already succeeded, even with the same `Idempotency-Key`, can return `400` because the credit it took is already gone. Before retrying a clawback that may have succeeded, check `GET /billing-customers/{provider_customer_id}/balance-transactions` for it. A same-key retry of a credit is deduplicated.



## OpenAPI

````yaml /openapi.json post /billing-customers/{provider_customer_id}/balance-transactions
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:
  /billing-customers/{provider_customer_id}/balance-transactions:
    post:
      tags:
        - Billing Customers
      summary: Create Balance Transaction
      description: >-
        Grants account credit to one of your billing customers, or claws unused
        credit back. `amount` uses the payment provider's sign, the same
        convention as the billing customer's `balance`: **a negative amount
        grants credit (at most `10000`, $100.00 in USD, per request), and a
        positive amount claws credit back (at most the remaining credit, so the
        balance never goes above `0`)**. The grant itself is not invoiced: the
        credit appears on the invoice it pays, and `description` / `metadata`
        record why it was granted. The part of an invoice paid with credit is
        refunded back to the balance, not to the card, with `balance_amount` on
        `POST /invoices/{provider_invoice_id}/refunds`. Concurrent clawbacks for
        the same customer are not serialized.


        **Retrying a clawback.** The remaining-credit check runs against the
        live balance before the request reaches the payment provider, so
        retrying a clawback that already succeeded, even with the same
        `Idempotency-Key`, can return `400` because the credit it took is
        already gone. Before retrying a clawback that may have succeeded, check
        `GET /billing-customers/{provider_customer_id}/balance-transactions` for
        it. A same-key retry of a credit is deduplicated.
      parameters:
        - in: path
          name: provider_customer_id
          required: true
          schema:
            type: string
          description: Provider customer ID. Must belong to your own configuration.
          example: test_customer_id
        - in: header
          name: Idempotency-Key
          required: false
          schema:
            type: string
          description: >-
            Deduplicates retried requests with the same key and parameters
            (about a 24-hour window), except a clawback retried after it
            succeeded, which can return `400`. Printable ASCII with no trailing
            whitespace. Keep it short (a UUID works): the key is scoped to the
            customer before it reaches the payment provider, and a key too long
            once scoped is a `400`. **Without a key a retry is not deduplicated
            and grants the credit twice**, so send one on every request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - amount
                - currency
                - description
              properties:
                amount:
                  type: integer
                  description: >-
                    Non-zero, in the smallest unit of `currency`. Negative
                    grants credit (at least `-10000`); positive claws credit
                    back (at most the remaining credit).
                currency:
                  type: string
                  description: >-
                    ISO currency code; lowercased server-side. For a clawback it
                    must match the customer's currency (`400` on a mismatch, or
                    when the customer has no currency yet). For a credit, use
                    the customer's currency.
                description:
                  type: string
                  description: >-
                    Why the credit is granted or taken back. Trimmed; 1–350
                    characters.
                metadata:
                  type: object
                  additionalProperties:
                    type: string
                  description: Free-form string key/value pairs stored on the transaction.
            example:
              amount: 300
              currency: usd
              description: Referral refunded
              metadata:
                provider_invoice_id: test_invoice_id
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      provider_balance_transaction_id:
                        type: string
                        description: Provider balance transaction ID.
                      provider_customer_id:
                        type: string
                        description: Provider customer ID.
                      amount:
                        type: integer
                        description: 'As sent: negative is a credit, positive is a clawback.'
                      currency:
                        type: string
                        description: Lowercase ISO currency code.
                      description:
                        type:
                          - string
                          - 'null'
                        description: As sent.
                      ending_balance:
                        type: integer
                        description: >-
                          The customer's balance after this transaction
                          (negative is credit available).
                      type:
                        type: string
                        description: >-
                          Transaction type from the payment provider, passed
                          through (for example `adjustment` for a transaction
                          created here, `applied_to_invoice` when credit pays an
                          invoice).
                      provider_invoice_id:
                        type:
                          - string
                          - 'null'
                        description: >-
                          The invoice the transaction relates to; `null` when it
                          is not tied to an invoice (for example an
                          `adjustment`).
                      created:
                        type: integer
                        description: Unix timestamp (seconds).
                      metadata:
                        type: object
                        additionalProperties:
                          type: string
                        description: As sent; `{}` when none.
              example:
                data:
                  provider_balance_transaction_id: test_balance_transaction_id
                  provider_customer_id: test_customer_id
                  amount: 300
                  currency: usd
                  description: Referral refunded
                  ending_balance: -200
                  type: adjustment
                  provider_invoice_id: null
                  created: 1300
                  metadata:
                    provider_invoice_id: test_invoice_id
        '400':
          description: >-
            Missing body; `amount` missing, zero or not an integer; a credit
            beyond `10000`; a clawback beyond the remaining credit (including a
            retry of a clawback that already succeeded); a clawback whose
            `currency` is not the customer's currency; missing `currency`;
            missing, blank or over-long `description`; `metadata` that is not an
            object or has non-string values; an `Idempotency-Key` that is too
            long once scoped, or not printable ASCII; or the payment provider
            rejects the request.
        '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: The customer was not found within your configuration.
        '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.