Financial API

The financial endpoints cover the ledger: transactions, credits, invoice items, payment methods, reconciliation, and reports. Most calls operate on money already owed or paid, so run them after a client and its contracts exist.

Calculate before you charge

POST /financial/billing/calculate returns what a client owes for a period without writing anything. Use it to preview a run, then commit through invoice and transaction endpoints. POST /financial/tax/calculate does the same for tax, and GET /financial/tax/rates lists the rates in effect.

Transactions and credits

Every money movement is a transaction. Post one with POST /financial/transactions, read it back from GET /financial/transactions/{id}, and amend it with PUT /financial/transactions/{id}. Credits have their own flow: list balances with GET /financial/credits, check headroom with POST /financial/credits/validate, then apply, transfer between clients, or issue a prepayment invoice through /financial/credits/apply, /financial/credits/transfer, and /financial/credits/prepayment.

curl https://algapsa.com/api/v1/financial/credits/apply \
  -H "X-API-Key: $ALGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "cl_3f9a2c",
    "invoice_id": "inv_8821",
    "amount": 15000
  }'

Invoices, reconciliation, reports

Add a line with POST /financial/invoices/{id}/items and lock the invoice with POST /financial/invoices/{id}/finalize. Reconcile a period through POST /financial/reconciliation/run and clear flagged items with POST /financial/reconciliation/{id}/resolve. For read-only views, hit GET /financial/reports/aging, /reports/balance, and /reports/analytics. The /financial/bulk/* endpoints batch invoices, transactions, and credits when you need to move many records at once.

List invoices and payment methods

GET /financial/invoices returns a paginated invoice list for the tenant. Narrow it with status (draft, sent, paid, overdue, and more), client_id, billing_cycle_id, a due-date or amount range, or has_credit_applied, and sort by fields like invoice_date or total_amount. GET /financial/payment-methods lists the methods on file: filter by type (credit_card or bank_account), client_id, or is_default. Soft-deleted methods are left out unless you set exclude_deleted=false.

Endpoints

Every endpoint links through to its full parameters, request and response schemas, and code samples.