Transaction diagnostics

Use read-only detail routes to investigate provider and billing state without relying on dashboard table summaries.

Transaction detail

const response = await fetch(
  "https://usagey.com/api/billing/transactions/txn_123?organizationId=org_123&env=sandbox",
  { credentials: "include" },
);

const detail = await response.json();

Transaction details include derived refund state, retry relationships, related transactions, receipt information, and linked webhook traces.

The detail response reads the transaction, related refund chain, webhook records, and developer events from one workspace-scoped transaction snapshot. This prevents diagnostics from combining records from different tenants or partially observing a concurrent local refund update.

Webhook detail

const response = await fetch(
  "https://usagey.com/api/billing/webhooks/wh_evt_123?organizationId=org_123&env=sandbox",
  { credentials: "include" },
);

Webhook records expose signature validity, normalized provider event type, processing status, and correlation metadata. Invalid signatures are recorded as failures and do not mutate billing state.

Customer-portal diagnostics intentionally expose a narrower view. Receipt and invoice routes return documents only when the transaction or invoice belongs to the authenticated customer, and portal provider status excludes events that cannot be correlated to that customer's external billing identifiers.

Rate-limit diagnostics

Usage, checkout, checkout confirmation, webhooks, refunds, authentication-sensitive operations, and billing API-key issuance use distributed rate limits. A depleted budget returns 429 with RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, and Retry-After headers.

Production deployments fail closed with 503 when the configured Redis limiter is unavailable. Confirm both UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN are present before investigating the protected handler itself.