Funding and billing

Fund one workspace balance for your agents, or give customers their own balances and charge for usage at your prices. Locus handles top-ups, metering, and the transaction history.

Choose a funding model

Model	How it works	Best for
You fund usage	Top up the workspace pool; calls deduct the base price	Internal agents or usage included in your product price
You bill customers	Collect payment through your own billing, then allocate pool credits to customers	Products with an existing billing system
Customers top up through Locus	Embed the billing widget or send a hosted checkout link	Adding prepaid usage billing to your app

For self-serve Locus Pro funding, see Account and usage.

Fund your workspace

Open Funding & billing → Funding, choose an amount, and complete Stripe Checkout. The minimum top-up is $5. Credits become available after payment is confirmed.

Create a checkout link from your server

curl --fail-with-body -X POST "https://api.paywithlocus.com/api/credits/topups" \
  -H "Authorization: Bearer $LOCUS_SECRET_KEY" \
  -H "Idempotency-Key: workspace-topup-1" \
  -H "Content-Type: application/json" \
  -d '{
    "usd": "100.00",
    "successUrl": "https://yourapp.com/billing?ok=1",
    "cancelUrl": "https://yourapp.com/billing"
  }'

Send the buyer to the returned url.

Confirm funding from the balance or a credits.topup.completed event. A browser redirect alone does not confirm payment.

Volume bonuses

Eligible enterprise pool top-ups include promotional credits. The default schedule is:

Pool top-up	Bonus
$500	5%
$1,000	10%
$5,000	15%
$10,000	20%

Use POST /api/credits/topups/quote to get the current total, including any bonus and processing fee. Personal and end-user top-ups do not earn volume bonuses.

Card processing fees

Choose whether buyers pay the processing fee separately or your workspace absorbs it. Display the returned quote so customers see the exact credits, fee, and total before paying.

Auto-recharge

Complete one manual top-up to save a reusable payment method, then set a balance threshold and refill amount in the dashboard. Changes require a workspace owner or admin with recent MFA or passkey verification. If the saved card fails, the dashboard alerts you. Calls can continue while enough credits remain.

Set a spending ceiling

Set a monthly hard cap, a monthly-spend email threshold, and a low-balance email threshold. The monthly cap follows the UTC calendar month and counts completed charges plus funds reserved for calls in progress. When a new call would exceed the cap, Locus rejects it before contacting the provider. Existing calls finish and settle normally. Raise the limit or wait for the next month to allow more spending. An owner or admin must complete recent MFA or passkey verification to change these controls. An API key cannot raise its own spending ceiling.

Fund customer balances

Let customers buy credits

The billing widget shows a customer’s balance and opens Locus-hosted Stripe Checkout. It uses a publishable key and a short-lived end-user token issued by your server. You can also create a checkout link with POST /api/credits/topups by including the customer’s externalUserId. Those credits belong to that customer and pay for calls at your configured price.

Allocate credits after your own billing

If you already charge customers, move credits from your pool to their balance:

curl --fail-with-body -X POST \
  "https://api.paywithlocus.com/api/credits/end-users/user_123/allocate" \
  -H "Authorization: Bearer $LOCUS_SECRET_KEY" \
  -H "Idempotency-Key: allocate-user-123-1" \
  -H "Content-Type: application/json" \
  -d '{"credits":"5000"}'

Allocation moves existing credits; it does not charge a card. Use deallocate to return unused credits to the pool. When allocated credits are spent, the markup portion returns to your pool.

Collect earnings

When customers buy credits through Locus-hosted checkout, your markup accrues as payable earnings as they use those credits. Margin matures after a holdback period, 30 days by default, and eligible payouts are processed after review. Open Funding & billing → Payouts to connect a Stripe account for bank payouts or set a USDC address on Base. The dashboard shows accrued and payable earnings. Payouts require an active commercial agreement; evaluation workspaces cannot receive them. Payout-destination changes require an owner or admin through the dashboard with recent MFA or passkey verification. Changing a USDC address starts a 24-hour hold before the next payout. If you collect customer payments yourself and allocate credits, you already hold the cash margin. That model does not create a Locus margin payout.

Refunds and disputes

Event	Result
Non-streaming call fails before success	The credit reservation is released
Stream fails before provider acceptance	The reservation is released
Accepted stream later disconnects or fails	The call remains charged
Balance is insufficient	The call does not run or charge
Same request is retried with the same idempotency key	The original result is replayed without a second charge
Customer disputes a Locus-hosted top-up	Disputed credits are reclaimed and the account freezes; a favorable resolution reverses this

Disputes on payments you collect through your own Stripe account remain under your billing policy.

Follow payments with webhooks

Configure a webhook URL in the dashboard to receive top-up, charge, refund, balance, and dispute events. Use them to update your product after payment confirmation or notify a customer when their balance is low. Verify each delivery’s signature against the raw request body, reject stale timestamps, and deduplicate by event ID. The API reference and signed fixtures cover verification and payloads.

Review transactions

Open Activity to trace top-ups, charges, allocations, refunds, and payouts. Filter by customer, agent, provider, endpoint, or your own attribution fields. For reporting, use GET /api/credits/ledger for entries and GET /api/credits/ledger/summary for totals. Financial history is append-only, so corrections remain visible as new entries.

Add the billing widget

Put balance display and top-ups in your app.

Set customer prices

Choose your credit denomination and markup.

Getting started

Build with Locus Pro

Connect agents

Funding & billing

Developer tools

Catalog directory

Testing

Choose a funding model

Fund your workspace

Volume bonuses

Card processing fees

Auto-recharge

Set a spending ceiling

Fund customer balances

Let customers buy credits

Allocate credits after your own billing

Collect earnings

Refunds and disputes

Follow payments with webhooks

Review transactions

Add the billing widget

Set customer prices

​Choose a funding model

​Fund your workspace

​Volume bonuses

​Card processing fees

​Auto-recharge

​Set a spending ceiling

​Fund customer balances

​Let customers buy credits

​Allocate credits after your own billing

​Collect earnings

​Refunds and disputes

​Follow payments with webhooks

​Review transactions

Add the billing widget

Set customer prices

Choose a funding model

Fund your workspace

Volume bonuses

Card processing fees

Auto-recharge

Set a spending ceiling

Fund customer balances

Let customers buy credits

Allocate credits after your own billing

Collect earnings

Refunds and disputes

Follow payments with webhooks

Review transactions