API Reference

Invoices

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Create Batch Get

POST/invoices/batch-get

Retrieves multiple invoices.

Body ParametersJSONExpand Collapse

ids: array of string

Invoice ids to retrieve. Up to 200 per request.

ReturnsExpand Collapse

data: object { invoices, not_found }

Result of a batch invoice retrieval.

invoices: array of Invoice { id, created, status, 5 more }

Invoices that were found, in request order.

balances: array of object { currency, net, payins, payouts }

Invoice-level balances by currency.

currency: string

ISO 4217 or crypto currency code.

net: object { actual, expected, remaining }

Net balance breakdown.

actual: string

Actual amount as a string in the smallest currency unit, such as cents for USD.

expected: string

Expected amount as a string in the smallest currency unit, such as cents for USD.

remaining: string

Remaining amount as a string in the smallest currency unit, such as cents for USD.

payins: object { actual, expected, remaining }

Payins balance breakdown.

actual: string

Actual amount as a string in the smallest currency unit, such as cents for USD.

expected: string

Expected amount as a string in the smallest currency unit, such as cents for USD.

remaining: string

Remaining amount as a string in the smallest currency unit, such as cents for USD.

payouts: object { actual, expected, remaining }

Payouts balance breakdown.

actual: string

Actual amount as a string in the smallest currency unit, such as cents for USD.

expected: string

Expected amount as a string in the smallest currency unit, such as cents for USD.

remaining: string

Remaining amount as a string in the smallest currency unit, such as cents for USD.

payments: array of object { amount, currency, posted, 3 more }

Payments allocated to the invoice.

amount: string

Amount allocated as a string in the smallest currency unit, such as cents for USD.

currency: "ADA" or "BTC" or "DAI" or 176 more

ISO 4217 or crypto currency code.

Accepts one of the following:

"ADA"

"BTC"

"DAI"

"ETH"

"SOL"

"USDC"

"USDT"

"USDG"

"EURC"

"CADC"

"CADT"

"XLM"

"UNI"

"BCH"

"LTC"

"AAVE"

"LINK"

"MATIC"

"PTS"

"AED"

"AFN"

"ALL"

"AMD"

"ANG"

"AOA"

"ARS"

"AUD"

"AWG"

"AZN"

"BAM"

"BBD"

"BDT"

"BGN"

"BHD"

"BIF"

"BMD"

"BND"

"BOB"

"BRL"

"BSD"

"BTN"

"BWP"

"BYR"

"BZD"

"CAD"

"CDF"

"CHF"

"CLP"

"CNY"

"COP"

"CRC"

"CUC"

"CUP"

"CVE"

"CZK"

"DJF"

"DKK"

"DOP"

"DZD"

"EGP"

"ERN"

"ETB"

"EUR"

"FJD"

"FKP"

"GBP"

"GEL"

"GGP"

"GHS"

"GIP"

"GMD"

"GNF"

"GTQ"

"GYD"

"HKD"

"HNL"

"HRK"

"HTG"

"HUF"

"IDR"

"ILS"

"IMP"

"INR"

"IQD"

"IRR"

"ISK"

"JMD"

"JOD"

"JPY"

"KES"

"KGS"

"KHR"

"KMF"

"KPW"

"KRW"

"KWD"

"KYD"

"KZT"

"LAK"

"LBP"

"LKR"

"LRD"

"LSL"

"LYD"

"MAD"

"MDL"

"MGA"

"MKD"

"MMK"

"MNT"

"MOP"

"MUR"

"MVR"

"MWK"

"MXN"

"MYR"

"MZN"

"NAD"

"NGN"

"NIO"

"NOK"

"NPR"

"NZD"

"OMR"

"PAB"

"PEN"

"PGK"

"PHP"

"PKR"

"PLN"

"PYG"

"QAR"

"RON"

"RSD"

"RUB"

"RWF"

"SAR"

"SBD"

"SCR"

"SDG"

"SEK"

"SGD"

"SHP"

"SLL"

"SOS"

"SPL"

"SRD"

"SVC"

"SYP"

"STN"

"SZL"

"THB"

"TJS"

"TMT"

"TND"

"TOP"

"TRY"

"TTD"

"TVD"

"TWD"

"TZS"

"UAH"

"UGX"

"USD"

"UYU"

"UZS"

"VEF"

"VND"

"VUV"

"WST"

"XAF"

"XCD"

"XOF"

"XPF"

"YER"

"ZAR"

"ZMW"

"LOGICAL"

"CUSTOM"

posted: string

Timestamp when the parent transaction was posted. Uses ISO 8601 format.

formatdate-time

transaction: object { id, external_id, tags }

Transaction the payment is applied to.

id: string

FRAGMENT generated unique ID.

external_id: string

User-provided unique ID.

tags: array of object { key, value }

Tags from the parent transaction.

key: string

Tag key.

value: string

Tag value.

type: "payin" or "payout"

Type of the payment.

Accepts one of the following:

"payin"

"payout"

user: object { id, external_id }

User associated with the payment.

id: string

FRAGMENT generated unique ID.

external_id: string

User-provided unique ID.

users: array of object { id, balances, external_id }

Users involved in the invoice.

id: string

User-provided unique external ID.

balances: array of object { currency, net, payins, payouts }

Per-currency balance breakdown for the user.

currency: string

ISO 4217 or crypto currency code.

net: object { actual, expected, remaining }

Net balance breakdown.

actual: string

Actual amount as a string in the smallest currency unit, such as cents for USD.

expected: string

Expected amount as a string in the smallest currency unit, such as cents for USD.

remaining: string

Remaining amount as a string in the smallest currency unit, such as cents for USD.

payins: object { actual, expected, remaining }

Payins balance breakdown.

actual: string

Actual amount as a string in the smallest currency unit, such as cents for USD.

expected: string

Expected amount as a string in the smallest currency unit, such as cents for USD.

remaining: string

Remaining amount as a string in the smallest currency unit, such as cents for USD.

payouts: object { actual, expected, remaining }

Payouts balance breakdown.

actual: string

Actual amount as a string in the smallest currency unit, such as cents for USD.

expected: string

Expected amount as a string in the smallest currency unit, such as cents for USD.

remaining: string

Remaining amount as a string in the smallest currency unit, such as cents for USD.

external_id: string

User-provided unique ID.

not_found: array of string

Ids from the request that did not match any invoice.

Create Batch Get

HTTP

HTTP

TypeScript

Python

curl https://api.us-west-2.fragment.dev/billing/invoices/batch-get \
    -H 'Content-Type: application/json' \
    -d '{
          "ids": [
            "string"
          ]
        }'

200 example

{
  "data": {
    "invoices": [
      {
        "id": "inv_1234567890",
        "created": "2024-01-13T00:00:00Z",
        "status": "active",
        "tags": [
          {
            "key": "department",
            "value": "engineering"
          }
        ],
        "version": 1,
        "workspace_id": "ws_1234567890",
        "line_items": [
          {
            "id": "item_1234567890",
            "amount": "1000",
            "currency_code": "USD",
            "description": "Professional services for January 2026",
            "price": {
              "amount": "1000",
              "quantity": 1,
              "unit_price": "1000"
            },
            "product_id": "prod_1234567890",
            "tags": [
              {
                "key": "department",
                "value": "engineering"
              }
            ],
            "type": "payout",
            "user_id": "user_ext_456"
          }
        ],
        "modified": "2024-01-13T00:00:00Z",
        "balances": [
          {
            "currency": "USD",
            "net": {
              "actual": "5000",
              "expected": "10000",
              "remaining": "5000"
            },
            "payins": {
              "actual": "5000",
              "expected": "10000",
              "remaining": "5000"
            },
            "payouts": {
              "actual": "5000",
              "expected": "10000",
              "remaining": "5000"
            }
          }
        ],
        "payments": [
          {
            "amount": "150",
            "currency": "USD",
            "posted": "2024-01-13T00:00:00Z",
            "transaction": {
              "id": "txn_dHhuX2ZyYWdfMDAx",
              "external_id": "bank_txn_123",
              "tags": [
                {
                  "key": "department",
                  "value": "engineering"
                }
              ]
            },
            "type": "payin",
            "user": {
              "id": "user_abc123",
              "external_id": "user_ext_001"
            }
          }
        ],
        "users": [
          {
            "id": "user_ext_789",
            "balances": [
              {
                "currency": "USD",
                "net": {
                  "actual": "5000",
                  "expected": "10000",
                  "remaining": "5000"
                },
                "payins": {
                  "actual": "5000",
                  "expected": "10000",
                  "remaining": "5000"
                },
                "payouts": {
                  "actual": "5000",
                  "expected": "10000",
                  "remaining": "5000"
                }
              }
            ],
            "external_id": "user_ext_789"
          }
        ]
      }
    ],
    "not_found": [
      "string"
    ]
  }
}

Returns Examples

200 example

{
  "data": {
    "invoices": [
      {
        "id": "inv_1234567890",
        "created": "2024-01-13T00:00:00Z",
        "status": "active",
        "tags": [
          {
            "key": "department",
            "value": "engineering"
          }
        ],
        "version": 1,
        "workspace_id": "ws_1234567890",
        "line_items": [
          {
            "id": "item_1234567890",
            "amount": "1000",
            "currency_code": "USD",
            "description": "Professional services for January 2026",
            "price": {
              "amount": "1000",
              "quantity": 1,
              "unit_price": "1000"
            },
            "product_id": "prod_1234567890",
            "tags": [
              {
                "key": "department",
                "value": "engineering"
              }
            ],
            "type": "payout",
            "user_id": "user_ext_456"
          }
        ],
        "modified": "2024-01-13T00:00:00Z",
        "balances": [
          {
            "currency": "USD",
            "net": {
              "actual": "5000",
              "expected": "10000",
              "remaining": "5000"
            },
            "payins": {
              "actual": "5000",
              "expected": "10000",
              "remaining": "5000"
            },
            "payouts": {
              "actual": "5000",
              "expected": "10000",
              "remaining": "5000"
            }
          }
        ],
        "payments": [
          {
            "amount": "150",
            "currency": "USD",
            "posted": "2024-01-13T00:00:00Z",
            "transaction": {
              "id": "txn_dHhuX2ZyYWdfMDAx",
              "external_id": "bank_txn_123",
              "tags": [
                {
                  "key": "department",
                  "value": "engineering"
                }
              ]
            },
            "type": "payin",
            "user": {
              "id": "user_abc123",
              "external_id": "user_ext_001"
            }
          }
        ],
        "users": [
          {
            "id": "user_ext_789",
            "balances": [
              {
                "currency": "USD",
                "net": {
                  "actual": "5000",
                  "expected": "10000",
                  "remaining": "5000"
                },
                "payins": {
                  "actual": "5000",
                  "expected": "10000",
                  "remaining": "5000"
                },
                "payouts": {
                  "actual": "5000",
                  "expected": "10000",
                  "remaining": "5000"
                }
              }
            ],
            "external_id": "user_ext_789"
          }
        ]
      }
    ],
    "not_found": [
      "string"
    ]
  }
}