Welcome to Revinci

Revinci is the revenue platform built for the agentic economy — price, bill, and protect margin on every AI agent, with real-time cost intelligence behind every call. This guide walks you through setting up your workspace, building and pricing agents, selling to customers, and billing usage, in the order you'll actually do it.

How Revinci works

Every agent you sell moves through the same backbone. Set the foundations once, then repeat the middle two steps for every new agent you launch:

Two Revinci concepts sit behind all of this and are worth naming up front: SmartCost, which keeps a real-time read on what an agent actually costs to run (tokens, infra, third-party APIs), and SmartMargin, which compares that cost against what you charged — per account, per agent, per invoice — so margin leakage shows up before it becomes a quarter-end surprise.

Signing in

1. Open the sign-in page.

   Go to marketplace-workspace-dev.revinci.ai/auth/sign-in in your browser.

2. Enter your credentials.

   Type the email and password your workspace admin gave you, then click Login.

3. Land on the Dashboard.

   You'll arrive at your workspace's home dashboard, with the left-hand navigation ready to go.

Navigation map

Revinci's left sidebar is organized into two working areas — a top group for day-to-day selling and billing, and a Setup group for the configuration that powers pricing. A gear icon at the bottom opens Settings, where connectors, payments, API keys, and notifications live. Here's where everything is:

Every link in this guide points at your workspace's dev environment (marketplace-workspace-dev.revinci.ai). Swap the host for your production URL once you're ready to go live.

Set up the building blocks

Four things underpin every price and every cost model in Revinci: currency, units of measure, attributes, and cost profiles. Configure these once per workspace before you create your first agent.

Currency management

Currencies determine what your prices, costs, and wallet balances are denominated in. You need at least a base currency; add exchange rates the moment you sell or price in more than one.

Add a currency

1. Open Currency setup.

   Go to Setup ▸ Currency Management ▸ Currency.

2. Click + Currency.

   Pick a Currency from the ISO list (e.g. USD), give it a Currency Display Name, and check Is Base Currency for the one currency your organization reports in.

3. Add Currency.

   It appears in the table with its base-currency flag.

Add an exchange rate

1. Open Currency Exchange Rate.

   Setup ▸ Currency Management ▸ Currency Exchange Rate ▸ + Exchange Rate.

2. Set the pair and rate.

   Base Currency ISO Code, Target Currency ISO Code, the numeric Exchange Rate, and a Rate Type (e.g. Spot).

3. Set the effective window.

   Pick an Effective Date Range and, optionally, a Source for audit purposes, then Save.

Units of measure (UOM)

A Unit of Measure is the "per what" behind every price and every cost line — per token, per minute, per seat, per API call. Costs, rate matrices, and price lines all point back to a UOM.

1. Open Unit of Measure.

   Setup ▸ UOM ▸ Unit Of Measure ▸ + Unit Of Measure.

2. Name it and pick a family.

   Give it a Name (e.g. Per Token) and a UOM Family — the families you'll typically see are Storage, Time, and Weight, plus any custom families your workspace has added.

3. Create.

   It's now selectable everywhere a UOM field appears.

Unit of Measure Conversion

When your vendor prices in one unit but you sell in another — a provider bills per 1,000 tokens while you meter per token — use Setup ▸ UOM ▸ Unit Of Measure Conversion to define the conversion factor between a source and target UOM, so rate matrices and cost masters reconcile automatically.

Attributes & attribute groups

Attributes are the dimensions your pricing and cost matrices flex on — think of them as the column headers in a rate card. An Attribute is one reusable field with a set of values (a picklist, like Input Tokens / Output Tokens, or a numeric range). An Attribute Group bundles one or more attributes together so you can attach the whole set to a product or agent in one go.

Create an Attribute

1. Open Attribute.

   Setup ▸ Attribute ▸ + Attribute.

2. Name it and define its values.

   Give it a Name and Description, then define the attribute's values — a picklist (e.g. Input Tokens, Output Tokens) or a numeric range, depending on how the dimension should be sliced.

3. Save.

   The attribute is Active and ready to be grouped.

Create an Attribute Group

1. Open Attribute Group.

   Setup ▸ Attribute Group ▸ Create Attribute Group.

2. Name the group and add attributes.

   Give it a Name (e.g. LLM-AG), then click + Add Attribute and select the attribute(s) it should bundle (e.g. an attribute named LLM-A carrying the Input Tokens / Output Tokens values). Mark any attribute as required if the pricing model depends on it always being set.

3. Save.

   The group is now selectable wherever attribute-based pricing or matrix dimensions are configured — cost matrices, agent matrices, and attribute-based consumption pricing.

Cost profiles & LLM cost models

A Cost Profile is a named, versioned canvas — Draft, then Published — that models what an agent actually costs you to run. It's built from one or more cost nodes (an LLM cost model, a fixed price point, and so on), and once published it drives the live Estimated Cost badge you'll see while pricing an agent, plus SmartMargin reporting later.

1. Create the Cost Profile shell

1. Open Cost Profile.

   Setup ▸ Cost ▸ Cost Profile ▸ + Cost Profile.

2. Name it and set scope.

   Give it a Name, choose a Scope (typically Organization), and check Is Standard if this should be the default profile new agents fall back to.

3. Create.

   You land on the visual cost canvas in Draft — this is where you'll drop in cost nodes like LLM and New Price Point.

2. Build the LLM cost model

The cost model itself — what an LLM (or any infra line item) actually costs per unit — is built as a Product under Setup ▸ Cost ▸ Costs. Despite the internal label, this is exactly where you set up an LLM's cost, not a sellable product.

1. Open Costs and start a product.

   Setup ▸ Cost ▸ Costs ▸ + Create Product.

2. Product information.

   Name (e.g. the model name, like Opus-4.5), Product Code, Product Family, a Description, and optional #Tags for organizing your cost catalog.

3. Attach an Attribute Group.

   Pick the group that defines this cost model's pricing dimensions — e.g. LLM-AG, carrying Input Tokens / Output Tokens.

4. Set the Cost Master.

   Name, UOM (e.g. Per Token), Currency (e.g. USD), a Factor if your vendor's list price needs converting (e.g. 1,000,000 when the vendor prices per million tokens but your UOM is per token), Transaction Unit, and Is Active.

5. Add a Rate Matrix.

   Click + Add Matrix and step through the three-step wizard:

3. Publish the Cost Profile

Back on the Cost Profile canvas, confirm the LLM node points at the cost model you just built (add a New Price Point node for any secondary cost line, like a fixed per-session infra fee). Click Save as Draft while you're iterating, then Publish once it's ready — only Published profiles are selectable from an agent's Cost Profile field.

Creating an agent

In Revinci, the agent is the product. Creating one has three parts: describe it, define what success looks like (Value Outcomes), and decide how you'll charge for it.

1. Open the agent catalog.

   In the left sidebar, the entry labelled Products opens the Agents catalog — go to Agents ▸ Products, then click + Agent.

2. Choose an Agent Type.

   Simple Agent

   A standalone agent that performs one specific function independently.

   Workflow Agent

   A complex agent made of multiple tasks and an orchestrated process.

3. Fill in Agent Information.

   Agent Name, Agent Code (e.g. AGT-001), a Description, optional #Tags, and a Cost Profile — pick the Published profile you built in Foundations. As soon as enough fields are set, an Estimated Cost badge appears top-right and updates live.

4. Continue.

   Moves you into Outcomes and Pricing.

Value outcomes

An Outcome defines what "success" means for this agent — a resolved ticket, a booked meeting, a qualified lead — and what that success is worth, independent of how you eventually bill for it. Outcomes power delivered-value reporting, can appear directly on customer invoices, and can even become a pricing dimension in their own right (charge per outcome, not just per token).

1. Click + Add Outcome.

   Give it an Outcome ID (a short reference code, e.g. Per-API), an Outcome Name shown in reports and invoices, and a Value Cap — the maximum dollar value counted per occurrence, so a runaway formula can't blow past a sane ceiling.

2. Define Success Criteria.

   Add one or more conditions that must all be true for the outcome to count — pick a Field, an Operator, and a Value. Supported operator types include BOOLEAN (a true/false signal, e.g. ticket_resolved = true), EQUALS (an exact string or numeric match, e.g. deal_stage = proposal), and comparison operators like AT LEAST for numeric thresholds.

3. Add a Value Rule.

   Choose how this outcome is valued — you can add several rules per outcome, each independently capped:

value = (baseline_min − agent_field) ÷ 60 × hourly_cost
      ≤ Value Cap  per outcome (max)

# worked example
value = (45min − {processedAt}) ÷ 60 × $4.00/hr
      ≤ $3.00  per outcome (max)

4. Repeat for every outcome, then continue.

   An agent can carry multiple outcomes; each shows a compact summary chip (value-rule type, condition count, and cap) once saved — e.g. Time Based Percentage Formula 2 conditions CAP $1,000.00.

Pricing the agent

Use + Price Methods to attach one or more pricing blocks to the agent — you can combine a recurring platform fee with usage-based pricing on the same agent, the same way you'd pair a subscription with metered consumption.

Configuring a Consumption price

1. Name the price line.

   Set the Name shown in your catalog and reports, and the Transaction Unit (Currency, Token, Credit…).

2. Decide whether to set a price.

   Leave I Want to Set Price unchecked if this consumption is metered only to draw down a wallet, with no separate line-item charge. Check it to price it directly — then set Selling Frequency, Selling Model, and Price UOM.

3. Pick a Pricing Model.

   Flat

   One fixed price. No matrix required.

   Tiered

   Graduated or Volume tiers — set Min/Max Quantity and an Adjustment Type (Fixed or Percentage) per band.

   Attribute Based

   Recommended for consumption pricing. Choose the Selected Attributes — your Attribute Group, or a Value Outcome itself, so you can literally charge per outcome. Then set one price per Matrix Entry.

4. Optional add-ons.

   Add Minimum Commitment to guarantee a revenue floor, or configure a Free Tier with a Trial Unit and Trial Period.

5. Add Offerings (optional).

   Bundle this agent with others under + Add Offering if you sell it as part of a package.

6. Save.

   The agent appears in your catalog with a Pricing Methods badge, e.g. Consumption : Usage based, ready to be added to an order.

Customers (CRM)

Every order, wallet, and entitlement hangs off a Customer account. Create the account first, then everything else attaches to its Customer 360 record.

1. Open Customers.

   Agents ▸ Customers ▸ + Account.

2. Fill in Account Creation.

   Name, Account Number, Annual Revenue, Employees Count, Business Activities, Type (Customer/Partner/…), Tax Id Registration Number, Jurisdiction, Industry, Account Source, Account Manager, and Account Website.

3. Save.

   Opens the Customer 360 record, with tabs for Detail (Information, Address, Contact, Note, Opportunity, Legal Entity, Billing Preferences), Entitlement, Wallets, Customer 360, and Agent Dashboard.

4. Add contacts and addresses.

   From the Detail tab, + Add a Contact (Prefix, First/Last Name, Phone, Mobile, Email, Department, Title, License ID, Is Primary) or an Address (Address Type, Street, City, State, Country, Postal Code).

Order creation flow

An Order is the quote-to-close object — what a customer is buying, on what terms. Finalizing one automatically creates a linked Entitlement.

Entitlement activation flow

1. Find the entitlement.

   Go to Agents ▸ Entitlements. The record created by your order shows Source: Order, linked back to it.

2. Activate.

   Open the entitlement, click Activate, choose an Activation Date on the calendar, and confirm.

3. Validate the Plan.

   Under the entitlement's Plan, check the Plan Lifecycle, Aggregators, Matrix, Transaction, and Billing Schedules tabs — confirm Pricing Method, Billing Frequency, Selling Term, Net Unit Price (shows Usage based for consumption), Currency, and Quantity are all correct, and that the Plan Lifecycle timeline shows the new plan active with a scheduled end date.

Usage ingestion & rating

Usage reaches Revinci one of two ways: push it yourself via the Usage Ingestion API, or connect an LLM Provider connector (see Integrations) so Revinci reads token counts and spend on a schedule without touching your application code.

Once ingested, Revinci meters and rates each event against the agent's rate matrix / cost master, draws down any linked wallet, and rolls it up into the plan's Aggregators. See Usage Ingestion in the API Reference for the full request/response shape.

Invoices & events

1. Generate a manual invoice.

   Agents ▸ Invoices ▸ Generate Manual Invoice, select the relevant entitlement or plan, and generate.

2. Validate.

   Confirm the invoice reflects usage-based totals for consumption agents, or fixed charges for subscription/one-time agents, then cross-check aggregated totals against the Billing Dashboard.

3. Troubleshoot with Events.

   Agents ▸ Events shows raw ingested usage as it lands — the first place to look if usage isn't showing up on an invoice.

Pause & resume a plan

Pausing suspends billing and usage rating for a plan without canceling it — useful for a seasonal hold or a customer request to skip part of the term. Both actions live on the entitlement's Pause and Resume buttons, top-right of the entitlement record.

1. Click Pause.

   Open the entitlement (Agents ▸ Entitlements) and click Pause. Select the date from which billing and usage rating should stop, then Confirm. Example: on a 1-year plan you want to pause for 2 months — pick that pause start date and confirm.

2. Resume becomes enabled.

   Once a plan is paused, the Resume button activates. Click it, select the resume date — it must fall after the pause date — and Confirm.

3. Activate the resulting record.

   Both the pause and the resume actions create a new record under the entitlement's Plan Order tab. Open it and click Activate to apply the change.

4. Confirm it landed.

   Once activated, the pause — and later the resume — appears under the Transaction tab, and the Plan Lifecycle timeline reflects the paused/resumed window.

Cancel a plan

Open the entitlement and click Cancel. Confirm the action — the plan is canceled immediately, stopping billing and usage rating going forward. Cancellation isn't reversible from the UI; create a new order if the customer needs service to resume.

Add a product to an entitlement

Add another agent to an existing entitlement without creating a new order.

1. Click Add on Plans.

   On the entitlement, under the Plan panel, click Add.

2. Select the agent.

   Choose the agent (product) to add, and confirm.

3. Finalize.

   Finalize the newly added product the same way you'd finalize an order — once finalized, the plan shows up under the entitlement's Plans list.

Upsell & upgrade

Both actions start from the plan's detailed view — open a plan under the entitlement and look at the top of the page for Upsell and Upgrade.

Creating a wallet

A Wallet is a prepaid, decrementing balance — in Tokens, Credits, or Currency — tied to a Customer account. Use one to sell a prepaid credit bundle, or simply to track and cap spend across one or many agents.

1. Open the account's Wallets tab.

   From a Customer record, go to Customer 360 ▸ Wallets ▸ + Wallet.

2. Wallet Details.

   Name, Account, Transaction Unit (Token / Currency / Credit), Amount, and Status (starts as Draft). Toggle Carry Over, Top-up Allowed, and Allow Negative Balance as needed.

3. Expiration Logic.

   Set a Date Type and number of Days, or tie expiration to another object (e.g. the linked Revenue Entitlement's end date).

4. Consumption Rule.

   Transaction Unit, Currency, Total Credit, a Valid From / Valid To window, and a Type:

   Discrete

   A fixed conversion, e.g. $200 = 3,000 Credits. Direct mapping between currency and credits.

   Range

   Variable, slab-based pricing — for tiered billing scenarios where the rate changes by volume.

5. Allocations.

   For each product/agent this wallet pays for, set an Allocation Type, an Allocation %, the Product, and whether Over Usage is allowed.

   Total allocation across all products must equal 100% before the wallet can be saved. This is the single most common reason a new wallet won't save.

Activate & fund

Use Replenish for scheduled or automatic refills (for example, driven by a carryover rule) rather than a one-off manual top-up.

Carryover rules

If Carry Over is on, configure its frequency and limits before activating — configuring it afterward won't retroactively apply to cycles that have already elapsed.

Carryover Amount = Remaining Balance × Carryover Percentage
                    (capped at Max Carryover Amount)

# Example — Remaining Balance: 1,000 · Carryover %: 20%
Carryover Amount = 1,000 × 20% = 200

# Example with a cap — Max Carryover Amount: 150
Calculated: 200 → Final (capped): 150

The system evaluates the remaining balance, applies the rule, transfers the eligible amount into the next cycle, and records it as a CARRY_OVER transaction.

Usage & transactions

Every usage event maps to a Plan, a Product, and a Wallet, then deducts from the wallet's balance in real time. Because a wallet operates in its own Transaction Unit (often Credits) while a product's usage is priced in currency, the wallet's Consumption Rule converts one into the other automatically.

Worked example — metering a two-mode feature

Say a product supports two usage modes, each priced differently, against a wallet whose Consumption Rule maps 3,000 Credits = $200 (so 1 Credit ≈ $0.0667, and 1 USD ≈ 15 Credits):

TOP_UP                          +3,000  → Balance: 3,000
Usage (with extended processing)  −30    → Balance: 2,970
Usage (without extended)          −15    → Balance: 2,955
Usage (with extended processing)  −30    → Balance: 2,925

All product usage is billed in the product's currency and automatically converted into the wallet's transaction unit for deduction — you never have to reconcile the two by hand. View the running ledger at Wallet ▸ Transactions, with entries recorded latest-first and one of four types:

Usage that isn't tied to any wallet still bills normally: Entitlement → Billing Schedule → Update Usage produces a manual invoice the same way.

Alerts & notifications

Two triggers cover most wallet monitoring, both configured through the same Notification Rules engine (see Integrations):

Alerts can reach you through any combination of four channels:

⚠️ Wallet Alert
Account:  Acme Robotics
Wallet:   API Usage Wallet
Balance:  180 Credits   (Threshold: 200)
Action:   Please top up to avoid service interruption.

Connectors

Everything Revinci needs to talk to the outside world — your CRM, your e-signature tool, your LLM providers, your payment gateway, your notification channels — lives under Settings.

1. Open Connectors.

   Settings ▸ Connectors — tabs across the top let you switch between Salesforce, HubSpot, E-Sign, Email Services, and LLM Providers.

2. Configure a CRM connector.

   For Salesforce or HubSpot, click Edit and fill in Environment (Production/Sandbox), Username, Password, Client ID, Client Secret, and Security Token. Once saved, secrets are masked in the UI.

3. Connect an LLM Provider.

   Under the LLM Providers tab, click Connect your first provider. Usage is then read on a schedule, so token counts and spend start arriving on the next heartbeat without any application changes. If your app already reports its own usage through the ingestion API or SDK, you don't need a connector — connectors exist for routes that can't otherwise attribute usage to individual agents.

Payment gateways

Configure Stripe, PayPal, and other gateways at Settings ▸ Payment Methods.

Webhook configuration

Copy your gateway's webhook URL into its dashboard so Revinci receives payment events:

https://api-dev.revinci.ai/revenue-management/api/v1/webhooks/stripe

• Keys are stored encrypted — Revinci never displays a saved secret in plain text again.
• Use test keys in development and live keys in production; keep the two environments on separate gateway records.
• Only one gateway can be marked primary at a time.
• Auto-retry and dunning behavior can be configured per gateway.

API keys

API keys authenticate every server-to-server call into Revinci — usage ingestion included. Manage them at Settings ▸ API Keys.

1. Click + Create API Key.

   Give it a Name and optional Description, a Rate Limit (blank = no rate limit), and an Expiration window (e.g. 30 days).

2. Copy the key immediately.

   It's shown once at creation — store it server-side and never expose it in client code. If it's lost, revoke it and create a new one.

3. Use it as a bearer token.

   Every subsequent API call sends it as Authorization: Bearer <token>.

Notification channels

Connect the destinations alerts can be sent to at Settings ▸ Notification Channels — Slack, Microsoft Teams, Google Chat, and email are all supported.

Slack setup

1. Enable Incoming Webhooks in Slack.

   In Slack, go to Apps ▸ Incoming Webhooks, enable them, and copy the generated Webhook URL.

2. Add the channel in Revinci.

   Back in Settings ▸ Notification Channels, add a Channel Name and paste the Webhook URL.

{
  "channel": "#wallet-alerts",
  "webhookUrl": "https://hooks.slack.com/services/T000/B000/XXXX"
}

💬  Wallet Alert Notification
Account:   Acme Robotics
Wallet:    Token Wallet
Event:     Low Balance Alert
Balance:   150 Tokens   (Threshold: 200)
Please top up to avoid service interruption.

Notification rules

Notification Rules are the single engine behind every alert in this guide — one rule can fan out to several channels at once. Manage them at Settings ▸ Notification Rules.

1. Click + Notification Rule.

   Give it a Rule Name, an Entity Type (Wallet, Order, Invoice, …), and an Event Type (Low Balance, Usage Threshold, …).

2. Pick channels and a recipient.

   Enable any combination of In-App, Email, Slack, or Teams, and set the Recipient Type (e.g. Account Owner, Admin group).

3. Save and confirm Status is Enabled.

   The rule now fires the moment its event condition is met — no need to touch it again per wallet or per order.

Events

Events are how you track usage and outcomes in your products. Send an event when a tracked action happens in your product so Revinci can attribute activity, calculate billing, and provide analytics.

Event attribution & billing

You can start sending events at any time. For events to be attributed, you need a customer and a product. For events to be used for billing, you also need an active order that connects the customer to the product.

Getting started

1. Create a product with usage-based or outcome-based pricing.

   Navigate to Products and create a product. Add usage-based or outcome-based pricing with an event name (e.g., api_calls, tokens_used). This event name is what you'll use when sending events.

2. Get your API key.

   Navigate to Settings ▸ API Keys and click + Create API Key. Give it a name, set an Expiration date, then Generate — copy the key immediately, since it's shown only once and identifies your organization.

3. Install the SDK.

   Install the Revinci SDK for your language. Revinci supports Java and Python, and any other stack can post directly to the REST API.

<dependency>
    <groupId>ai.revinci.platform</groupId>
    <artifactId>usage-ingestion-sdk</artifactId>
    <version>0.0.2-SNAPSHOT</version>
</dependency>

implementation 'ai.revinci.platform:usage-ingestion-sdk:0.0.2-SNAPSHOT'

import ai.revinci.sdk.usage.Revinci;

// Initialize the client - close it when your application shuts down
Revinci revinci = Revinci.builder()
    .apiKey("rvc_live_YOUR_API_KEY")  // Your API key from Settings
    .baseUrl("https://api.revinci.ai")
    .tenantId("your-tenant-id")
    .build();

// Make your LLM call exactly as you do today
Message response = anthropic.messages().create(...);

// Send the raw response - Revinci extracts tokens and model server-side
Map<String, String> metadata = Map.of(
    "agent", "support-bot",
    "session_id", "sess_123");

String idempotencyKey = revinci.usage()
    .track("PLAN_12345", response, "customer@example.com", metadata);

// Anthropic (the default for track)
revinci.usage().track("PLAN_12345", anthropicResponse);

// OpenAI
revinci.usage().trackOpenAI("PLAN_12345", openaiResponse, "customer@example.com");

// Azure OpenAI - your existing deployment credentials are all you need
revinci.usage().trackAzureOpenAI("PLAN_12345", azureResponse);

// Google Gemini
revinci.usage().trackGemini("PLAN_12345", geminiResponse);

import ai.revinci.sdk.usage.model.UsageEvent;
import ai.revinci.sdk.usage.model.BulkUsageResponse;
import java.util.ArrayList;
import java.util.List;

List<UsageEvent> events = new ArrayList<>();

for (ChatCompletion response : responses) {
    events.add(UsageEvent.builder()
        .provider("openai")
        .planNumber("PLAN_12345")
        .customerId("customer@example.com")
        .apiResponse(objectMapper.convertValue(response, Map.class))
        .metadata(Map.of("agent", "support-bot"))
        .build());
}

// Send all events in one request (1-1000 per batch)
BulkUsageResponse result = revinci.usage().trackBulk(events);
System.out.println(result.getSuccessCount() + " / " + result.getTotalEvents());

// Long-lived: close on application shutdown
revinci.close();

// Short-lived: try-with-resources closes it for you
try (Revinci revinci = Revinci.builder()
        .apiKey("rvc_live_YOUR_API_KEY")
        .baseUrl("https://api.revinci.ai")
        .tenantId("your-tenant-id")
        .build()) {

    revinci.usage().track("PLAN_12345", response);
}

pip install revinci-sdk

# From a checkout of the platform repository
cd commons/usage-ingestion-sdk-python
pip install -e .

curl -X POST https://api.revinci.ai/api/v1/usage/ingest \
  -H "Authorization: Bearer rvc_live_YOUR_API_KEY" \
  -H "Tenant-Id: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "azure_openai",
    "planNumber": "PLAN_12345",
    "customerId": "customer@example.com",
    "metadata": { "agent": "support-bot", "session_id": "sess_123" },
    "apiResponse": {
      "id": "chatcmpl-abc123",
      "model": "gpt-4o",
      "usage": {
        "prompt_tokens": 150,
        "completion_tokens": 75,
        "total_tokens": 225
      }
    }
  }'

{
  "message": "Raw usage data ingested successfully",
  "idempotencyKey": "azure_openai_PLAN_12345_chatcmpl-abc123_1730000000",
  "status": "accepted"
}

Wallet & Usage API

Wallet provisioning spans several dependent endpoints that must be called in the right order. Read this reference top to bottom the first time; afterwards, use the execution workflow below as your checklist.

Authentication & headers

Every request must include the headers below. Requests without a valid bearer token and tenant ID are rejected.

Execution workflow

The recommended end-to-end sequence — each stage's Action advances setup, and its Retrieve call verifies what you just configured.

Endpoint reference

Every endpoint, grouped by area. Methods, paths, and dependency notes below; the most-used calls include full sample payloads.

CRM Account APIs

{
  "name": "Acme Global Bank",
  "accountNumber": "ACME-001",
  "annualRevenue": 1200,
  "employeesCount": 120,
  "businessActivities": "Multinational banking and financial services",
  "type": "customer",
  "jurisdiction": "SINGAPORE",
  "industry": "banking",
  "accountSource": "CRM",
  "accountManager": "<userId>",
  "accountWebsite": "acmeglobalbank.example",
  "tags": []
}

Revenue & Rating APIs

Wallet APIs

{
  "name": "Acme Wallet — Video Interview",
  "accountId": "{accountId}",
  "transactionUnit": "TOKEN",
  "balance": 20000,
  "status": "Draft",
  "carryOver": true,
  "topupAllowed": true,
  "allowNegativeBalance": true,
  "expirationObject": "revenue_entitlement_end_date",
  "expirationObjectId": "{revenueEntitlementId}",
  "expirationLogic": 0
}

{
  "allocation": 100,
  "priceListItemId": "{priceListItemId}",
  "overuserallowed": true,
  "type": "percentage",
  "scope": "wallet",
  "scopeValue": "{walletId}",
  "condition": "allocation"
}

{
  "transactionUnit": "CURRENCY",
  "currencyIsoCode": "USD",
  "totalCredit": 10,
  "validFrom": 1775068200000,
  "validTo": 1806517800000,
  "type": "discrete",
  "price": 1,
  "scope": "wallet",
  "allocation": 0,
  "balance": 0,
  "scopeValue": "{walletId}",
  "condition": "consumption"
}

{
  "walletId": "{walletId}",
  "carryOverFrequency": "wallet_end_date",
  "carryOverPercentage": 100,
  "carryOverMaxAmount": "",
  "isActive": true
}

// Response
{
  "id": "{walletId}",
  "status": "ACTIVE",
  "accountId": "{accountId}",
  "balance": 20000,
  "carryOver": true,
  "transactionUnit": "CREDIT",
  "allowNegativeBalance": true
}

{
  "id": "{walletId}",
  "amount": 100
}

{
  "provider": "anthropic",
  "planNumber": "EXT_PLAN000117",
  "customerId": "",
  "customerEmail": "",
  "externalAccountId": "",
  "apiResponse": {
    "id": "",
    "model": "",
    "usage": {
      "input_tokens": 0,
      "output_tokens": 0,
      "cache_read_input_tokens": 0
    }
  },
  "metadata": {
    "session_id": "001",
    "agent_name": "",
    "department": "",
    "channel": "",
    "outcome_id": "With extended processing (90 min)",
    "source_platform": "Revinci_Usage"
  },
  "eventTimestamp": 1782888678000
}

// Response
{
  "idempotencyKey": "anthropic_EXT_PLAN000117__1782888678000",
  "message": "Raw usage data ingested successfully",
  "status": "accepted"
}

Revenue Entitlement, Plan & Pricing APIs

{
  "name": "Entitlement — Acme Robotics",
  "rateType": "BUDGETED",
  "priceProtectionDate": 1782864000000,
  "status": "Created",
  "accountId": "{accountId}",
  "currencyId": "{currencyId}",
  "startDate": 1782777600000,
  "endDate": 1814313599999,
  "expirationDays": 365,
  "paymentTerm": "30Days",
  "profileId": "{costProfileId}"
}

Recommended order end to end: Create Wallet → Carryover Frequency (if applicable) → Allocation → Consumption Rules → Activate → Top-Up → Usage Ingestion. Sample IDs throughout are illustrative — substitute your own accountId, walletId, planId, and priceListItemId.

Glossary

Agent

Revinci's sellable product — a Simple or Workflow agent with its own outcomes, pricing, and cost profile.

Cost Profile

A versioned (Draft → Published) container of cost nodes that models what an agent actually costs to run.

Cost Master / Costs

The LLM or infra cost model itself — UOM, currency, factor, and a rate matrix priced per attribute.

Attribute / Attribute Group

A reusable pricing dimension (Attribute) and a bundle of them attached to a product or agent (Attribute Group).

Rate Matrix

A table of prices keyed by attribute value — how a cost or price varies across dimensions like input vs. output tokens.

Outcome / Value Rule

A definition of agent "success" (Outcome) and how much that success is worth (its Value Rule: Time Based, Tiered, Percentage, or Formula).

Order

What a customer is buying and on what terms — becomes an Entitlement once finalized.

Entitlement / Plan

The activated grant a customer holds; its Plan carries pricing, billing schedule, and usage aggregation.

Wallet

A prepaid, decrementing balance (Token / Currency / Credit) tied to an account, drawn down by usage.

Consumption Rule

How a wallet converts priced usage into its own transaction unit (Discrete = fixed mapping, Range = tiered).

Allocation

The percentage of a wallet assigned to pay for a given product — must total 100% across all products before saving.

Troubleshooting & best practices

• Always activate a wallet only after Allocation (and Carryover / Consumption Rules, if applicable) are complete.
• Maintain 100% allocation at all times — partial allocation blocks saving.
• Test a new pricing model or wallet with a small usage event before rolling it out broadly.
• Enable alerts early, not after the first low-balance incident.
• Monitor through both the UI and the API — the Events and Transactions views catch what a dashboard summary can miss.