Neruba request flows
Neruba Billing Engine makes the core integration path concrete: authenticate, create a project, issue access keys, send usage, apply credits, and read billing state.
Projects, memberships, and scoped credentials define who can act.
Usage ingest and billing runs stay deterministic under retries.
Wallets, credits, and payment-linked state remain auditable.
Support workflows and readiness checks keep teams in control.
Copy the first request loop, then move on
Use examples when the team needs concrete requests instead of another conceptual page. Start with auth and project setup, make replay-safe writes obvious, then verify the resulting billing state before moving to rollout planning.
- An engineer needs copyable requests for the first production-minded integration loop.
- You want the write path and the read-back proof in one place instead of spread across docs.
- A team needs to see how tenancy, scoped keys, ingest safety, and billing reads fit together quickly.
- 1Authenticate and create the project boundary before usage traffic starts.
- 2Issue the project access key and keep idempotent ingest visible next to the sample requests.
- 3Read balances or billing state so the write path ends in financial state people can explain.
Bring the stack up first when you need a working environment before wiring requests.
Map event shape, rollout order, and production risk after the first loop works.
Check deployment, scheduler, webhook, and support posture before production traffic arrives.
See the request sequence before you implement it
Authenticate, create the project, issue the project API key, send usage or charge events, then inspect balances and billing state.
Start with operator access when you need to create projects and inspect state.
Establish the tenant boundary before machine traffic enters the system.
Issue the project-scoped key the integration will use.
Send a replay-safe event with a stable idempotency key.
Walk the first production integration before you wire everything
Neruba feels more credible when the first implementation path is obvious: establish the project boundary, issue the scoped key, send replay-safe writes, then prove the resulting financial state with reads your team can share.
The examples should keep tenancy and project-scoped access obvious before usage traffic enters the system.
Show idempotency and replay handling as part of the request story, not as a buried caveat after the sample code.
Balance, ledger, and billing reads matter because teams need proof that writes lead to understandable financial state.
Quickstart, implementation, and operations should feel like the natural next pages after the first API walkthrough works.
Confirm the project boundary and the key scopes before any ingest traffic is live.
Pair every usage or charge write with stable IDs so retries stay safe.
Check balances, ledger entries, or billing overview so the write has visible financial consequences.
Keep a copyable request trail the next engineer or operator can understand quickly.
The service returns the expected status and request identifiers.
Wallet, ledger, or billing overview data reflects the change you expected.
A repeated request does not create double-usage or duplicate money movement.
Another teammate can follow the request and output trail without guesswork.
Use the examples to prove that writes create financial state your team can explain
The strongest example sets do more than show request bodies. They help teams check that idempotent writes become visible wallet, ledger, or billing state that support and finance can follow.
Keep project context, API-key ownership, and tenant boundaries obvious before usage traffic ever enters the system.
Idempotency and replay handling should sit next to the ingest examples so retries feel designed, not accidental.
Balance, ledger, and billing reads prove that the requests create understandable financial state after the write path succeeds.
Quickstart, implementation, and operations become natural next steps once the request loop is visible and concrete.
Turn the example set into a playbook your team can follow
Instead of treating the examples like isolated endpoints, this section frames them as the first implementation checklist: set scope, protect writes, verify financial state, and hand the flow to the next engineer without guesswork.
Confirm the project boundary and the key scopes before any ingest traffic is live.
Pair every usage or charge write with stable IDs so retries stay safe.
Check balances, ledger entries, or billing overview so the write has visible financial consequences.
Keep a copyable request trail the next engineer or operator can understand quickly.
1) Authenticate and create a project
Start with user auth, create a project, and establish the tenant boundary before any usage or billing activity begins.
2) Issue a project access key
Create a project-scoped API key once, store it safely, and use it for metering or charge endpoints.
3) Send usage or charges
Record usage events or debit credits through replay-safe ingest endpoints so retries and late delivery stay manageable.
4) Read balances and billing state
Pull wallet, transaction, and billing overview data when customers, finance, or support need the current picture.
Copyable request flows for the core integration path
Authenticate
Use the main auth flow to get an access token for project setup and admin-side actions.
curl -X POST https://billing.example.com/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "owner@example.com",
"password": "strong-password"
}'Create a project and access key
Once authenticated, create the customer project and issue a project access key. The plaintext access key is shown once and should be stored immediately.
curl -X POST https://billing.example.com/projects \
-H "Authorization: Bearer <access-token>" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Production",
"externalKey": "acme-prod"
}'
# then create a project access key
curl -X POST https://billing.example.com/projects/<projectId>/access-keys \
-H "Authorization: Bearer <access-token>" \
-H "Content-Type: application/json" \
-d '{
"name": "Usage ingest",
"scopes": ["ingest:usage", "ingest:charge"]
}'Send usage events
Use the project access key on ingest endpoints. Idempotency keys keep retries and queue replays from double-applying usage.
curl -X POST https://billing.example.com/ingest/usage \
-H "x-api-key: <project-api-key>" \
-H "Idempotency-Key: evt_2026_03_17_001" \
-H "Content-Type: application/json" \
-d '{
"metricKey": "api_tokens",
"units": "1250.000000",
"timestamp": "2026-03-17T10:15:00.000Z"
}'Apply credits or read billing state
Use credit and read endpoints when you need to preload balances, inspect transactions, or show the current billing picture to operators or customers.
# grant credits
curl -X POST https://billing.example.com/projects/<projectId>/transactions/credit \
-H "Authorization: Bearer <access-token>" \
-H "Idempotency-Key: credit_2026_03_17_001" \
-H "Content-Type: application/json" \
-d '{
"amount": "100.000000",
"description": "Launch credit"
}'
# read billing overview
curl https://billing.example.com/projects/<projectId>/billing/overview \
-H "Authorization: Bearer <access-token>"Use these notes after the concrete request flows are clear and before you move into rollout work, so the technical guardrails stay separate from the sample request loop.
- Use user auth for project setup, operator actions, and billing reads.
- Use project access keys for ingest endpoints so metering traffic stays tenant-scoped.
- Store access keys immediately because plaintext values are only shown once.
- Treat docs and integration reference exposure as an environment decision, not a default production posture.
Move from sample requests into rollout work when the first loop is clear
Once the first request loop is clear, the next question is usually not another endpoint. It is whether the stack, rollout order, and operating model will hold up when the billing system meets real customer traffic.
Ask for rollout guidance when you want these request flows mapped to your product events, pricing rules, deployment posture, or migration plan.
Pressure-test the sample flows against the billing system you run
Neruba can map the sample requests to your pricing rules, event contracts, deployment posture, late-event handling, and migration constraints so implementation questions get answered against your real operating model.
Track accepted, replayed, and deduped writes before support has to guess what happened.
Keep malformed payloads, schema misses, and retry conflicts visible in one place.
Keep one known-good request sequence around so deploys and env changes are easy to verify.
Make it easy for the next engineer or operator to retrace the request path without reading source code first.