Credits and spend limits

Deeplinq owns a USD-pegged, append-only credit ledger. Credits and debits use integer micro-USD. The platform reserves a conservative amount before provider work and captures or releases it after actual usage is known.

Fund an organization

Platform administrators can grant credits directly:

curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: acme-contract-2026-07" \
  -X POST "$BASE_URL/v1/admin/orgs/$ORG_ID/credits" \
  -d '{"amount_micro_usd":100000000}'

The example grants USD 100. Reuse the same idempotency key when retrying the same business operation.

For a billing application, configure BILLING_TOKEN and call:

POST /v1/billing/topups
Authorization: Bearer <BILLING_TOKEN>
Idempotency-Key: <payment-provider>:<transaction-id>

The billing service verifies and owns payment-provider processing. Deeplinq records the paid amount and reference, but does not charge cards or call a PSP.

Monthly limits

An org-admin can set organization-wide defaults:

curl -H "Authorization: Bearer $ORG_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -X PUT "$BASE_URL/v1/limits" -d '{
  "soft_limit_micro_usd":50000000,
  "hard_limit_micro_usd":100000000
}'

Or override one attributed user:

curl -H "Authorization: Bearer $ORG_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -X PUT "$BASE_URL/v1/limits/user-42" -d '{
  "soft_limit_micro_usd":5000000,
  "hard_limit_micro_usd":10000000
}'

Soft limits warn without blocking. Hard limits return 402 before provider execution. Per-user limits apply only when the authenticated principal has a user subject, from a JWT, user-bound key, or trusted X-End-User-Id.

GET    /v1/limits
DELETE /v1/limits
DELETE /v1/limits/{user_id}

Inspect usage

Tenants read their balance and month-to-date breakdown:

GET /v1/usage

Platform administrators inspect all organization usage through the console or:

GET /v1/admin/usage

Usage includes request counts, token counts, spend, and per-model breakdown.

Reconciliation

Run the read-only reconciliation command against production data:

make billing-reconcile

It reports drift between the append-only ledger and maintained projections without changing financial state. Treat any drift as an incident and preserve the request IDs and audit export before remediation.

Failure behavior

• insufficient organization balance returns 402;
• a user hard limit returns 402;
• missing pricing returns 403 model_not_priced;
• a failed provider call may still settle reported partial usage exactly once;
• concurrent calls cannot spend the same scarce balance because reservations are transactional.