Billing actions

Billing action routes use the authenticated dashboard session and are restricted to organization owners and admins.

Issue pending invoices

const response = await fetch(
  "https://usagey.com/api/billing/invoices/issue-pending?organizationId=org_123&env=sandbox",
  { method: "POST", credentials: "include" },
);

Queue threshold overage

const response = await fetch(
  "https://usagey.com/api/billing/overage/settle-thresholds?organizationId=org_123&env=sandbox",
  { method: "POST", credentials: "include" },
);

This queues precise usage-ledger rows into provider-compatible settlement batches. It does not recognize revenue before provider confirmation.

Collect a settlement

const response = await fetch(
  "https://usagey.com/api/billing/overage/settlements/set_123/collect?organizationId=org_123&env=sandbox",
  {
    method: "POST",
    credentials: "include",
    headers: { "Idempotency-Key": crypto.randomUUID() },
  },
);

const { checkoutUrl } = await response.json();

Charge-direction settlements return a provider checkout URL. Credit-direction settlements allocate the credit newest-capture-first across prior settled usage charges from the same customer, currency, workspace, and provider connection. A credit can therefore create more than one provider refund.

Credit responses return 200 when every refund completes synchronously or 202 while provider webhooks are still reconciling. Usagey records each allocation before provider dispatch and will not automatically resend an allocation whose dispatch outcome is uncertain. If captured funds cannot cover the credit, the endpoint returns 409 with the remaining shortfall for operator review.

Completed provider refund transactions are the cash ledger entries. The completed credit settlement creates a zero-value aggregate audit marker so revenue and refund analytics do not count the same credit twice.

After checkout, a verified webhook or the checkout confirmation route reconciles the batch atomically.