API Reference

Invoices

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Search

POST/invoices/search

Searches invoices

Body ParametersJSONExpand Collapse

filter: object { status, tags }

Filter criteria for the search

status: optional "open"

Filter by invoice status. open returns invoices with non-zero clearing account balances.

tags: optional object { all, any }

Tag-based filter criteria. When both any and all are provided, results must match every entry in all AND at least one entry in any.

all: optional array of object { key, value }

Returns invoices matching every specified tag (AND).

key: string

Tag key to filter on. Must be an exact match; wildcards are not supported.

value: string

Tag value pattern to filter on. Supports wildcards: * matches any characters, ? matches a single character. Use \* or \? to match literal asterisks or question marks. Use * to match any value for the given key.

any: optional array of object { key, value }

Returns invoices matching at least one of the specified tags (OR).

key: string

Tag key to filter on. Must be an exact match; wildcards are not supported.

value: string

Tag value pattern to filter on. Supports wildcards: * matches any characters, ? matches a single character. Use \* or \? to match literal asterisks or question marks. Use * to match any value for the given key.

page_info: object { after, limit }

Pagination parameters

after: optional string

Cursor for fetching the next page of results

limit: optional number

Number of results to return. Defaults to 20.

minimum1

maximum200

ReturnsExpand Collapse

data: object { invoices, page_info }

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

List of invoices matching the search criteria

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

Invoice-level balances by currency: payins, payouts, and net (payins - payouts)

currency: string

Currency code

net: object { actual, expected, remaining }

actual: string

Actual amount (represented as string)

expected: string

Expected amount (represented as string)

remaining: string

Remaining amount (expected - actual, represented as string)

payins: object { actual, expected, remaining }

actual: string

Actual amount (represented as string)

expected: string

Expected amount (represented as string)

remaining: string

Remaining amount (expected - actual, represented as string)

payouts: object { actual, expected, remaining }

actual: string

Actual amount (represented as string)

expected: string

Expected amount (represented as string)

remaining: string

Remaining amount (expected - actual, represented as string)

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

Transaction allocations (payments) associated with this invoice.

amount: string

Amount allocated in smallest currency unit as stringified bigint.

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

Currency code (ISO 4217 or crypto)

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

Posted timestamp of the parent transaction in ISO 8601 format.

formatdate-time

transaction: object { id, external_id, tags }

Reference to a transaction by encoded ID and external ID.

id: string

Encoded transaction ID.

external_id: string

External transaction ID.

tags: array of object { key, value }

Metadata tags from the parent transaction.

key: string

Tag key

value: string

Tag value

type: "payin" or "payout"

The type of the payment.

Accepts one of the following:

"payin"

"payout"

user: object { id, external_id }

User reference in API responses: Fragment user id and external_id.

id: string

FRAGMENT generated ID of the user

external_id: string

External ID of the user

users: array of object { id, balances }

Users/parties involved in the invoice

id: string

User/party ID

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

Per-currency balance breakdown for this user

currency: string

Currency code

net: object { actual, expected, remaining }

actual: string

Actual amount (represented as string)

expected: string

Expected amount (represented as string)

remaining: string

Remaining amount (expected - actual, represented as string)

payins: object { actual, expected, remaining }

actual: string

Actual amount (represented as string)

expected: string

Expected amount (represented as string)

remaining: string

Remaining amount (expected - actual, represented as string)

payouts: object { actual, expected, remaining }

actual: string

Actual amount (represented as string)

expected: string

Expected amount (represented as string)

remaining: string

Remaining amount (expected - actual, represented as string)

page_info: object { next_cursor }

Pagination cursors.

next_cursor: optional string

Cursor to fetch the next page of results

Search

HTTP

HTTP

TypeScript

Python

curl https://api.us-west-2.fragment.dev/invoices/search \
    -H 'Content-Type: application/json' \
    -d '{
          "filter": {},
          "page_info": {}
        }'

200 example

{
  "data": {
    "invoices": [
      {
        "id": "inv_1234567890",
        "created": "2024-01-13T00:00:00Z",
        "status": "active",
        "tags": [
          {
            "key": "region",
            "value": "us-east"
          }
        ],
        "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": "region",
                "value": "us-east"
              }
            ],
            "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": "2026-02-12T00:00:00.000Z",
            "transaction": {
              "id": "txn_dHhuX2ZyYWdfMDAx",
              "external_id": "bank_txn_123",
              "tags": [
                {
                  "key": "region",
                  "value": "us-east"
                }
              ]
            },
            "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"
                }
              }
            ]
          }
        ]
      }
    ],
    "page_info": {
      "next_cursor": "next_cursor"
    }
  }
}

Returns Examples

200 example

{
  "data": {
    "invoices": [
      {
        "id": "inv_1234567890",
        "created": "2024-01-13T00:00:00Z",
        "status": "active",
        "tags": [
          {
            "key": "region",
            "value": "us-east"
          }
        ],
        "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": "region",
                "value": "us-east"
              }
            ],
            "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": "2026-02-12T00:00:00.000Z",
            "transaction": {
              "id": "txn_dHhuX2ZyYWdfMDAx",
              "external_id": "bank_txn_123",
              "tags": [
                {
                  "key": "region",
                  "value": "us-east"
                }
              ]
            },
            "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"
                }
              }
            ]
          }
        ]
      }
    ],
    "page_info": {
      "next_cursor": "next_cursor"
    }
  }
}