Quick Start

Use this guide to connect an application to Meterry from the Portal.

Concepts first

Meterry splits billing setup into a few stable objects. Understanding how they connect makes the rest of the quick start easier to follow.

Concept	What it solves	When to use it
Rule	Reads your raw usage JSON into a standard subject, dimensions, and charge items, with optional attached pricing.	Every usage integration needs at least one published extractor rule. Stable high-volume metrics such as tokens and requests should usually be priced directly in the extractor rule.
Account & Wallet	The account is who pays. The wallet is that account’s balance, available balance, and credit limit for one currency.	Use them for customer balances, top-ups, credit limits, realtime debit, balance webhooks, or organization/user/workspace spend tracking.
Subject Route	Routes the subject on a usage event to the account that should pay for it.	Use it when the usage producer and payer are not the same object, such as many users, agents, or API keys debiting one organization wallet.
Limit Control	Maintains realtime usage windows on a subject route, such as daily spend, weekly tokens, or one agent-task budget.	Use it when a user, API key, agent run, task, or organization member needs its own usage boundary in addition to account billing.

The smallest integration only needs a rule: Meterry can normalize events, produce charge items, and show usage in the Usage explorer. Add accounts, wallets, and subject routes when the system needs to know which wallet pays. Add limit control when individual subjects under that paying account need their own budgets.

Agent setup

If you are implementing the integration with Codex or another supported coding agent, install the Meterry skill first. The skill packages the billing model, endpoint order, wallet and route flow, and webhook handling rules in one place.

npx skills add meterry-com/skills --skill meterry

Start a fresh task or thread after installation so the agent picks up the skill.

Accounts can represent organizations or individual users

If your product bills individual users, the account’s primary subject can point directly at the platform user:

account: acct_user_001
primary subject: user/u_001
usage subject: user/u_001 -> acct_user_001

If your product bills organizations, let the account represent the organization:

account: acct_org_001
primary subject: org/org_001
wallet: acct_org_001 / USD

Users inside the organization can still be reported as separate usage subjects, then routed to the same organization account:

subject route: org_001_user/u_001 -> acct_org_001
subject route: org_001_user/u_002 -> acct_org_001

This pattern is useful when the same platform user ID can belong to multiple organizations. subject_type=org_001_user means “usage from this user inside org_001”, while subject_id=u_001 remains your platform user ID. The wallet debit belongs to the organization, but limit control can track org_001_user/u_001 and org_001_user/u_002 separately.

If your product already has a unique membership ID for each organization member, you can use that instead:

subject route: org_member/mem_001 -> acct_org_001

The rule of thumb is: accounts express the payer; subjects express the usage producer and limit target; subject routes connect the two.

After signing in, use the project selector in the top bar.

Open the project selector.
Choose Create project.
Enter a name such as Production or Staging.
Save the project.

After at least one project exists, Portal pages are scoped by URL:

/projects/:projectId

This makes refreshes and shared links reopen the same workspace.

2. Create an API key

Open API keys from the sidebar.

Select Create key.
Use a name that identifies the integration, for example Production gateway.
Select the least privilege scopes the service needs. For ingestion, include usage:ingest.
Create the key and copy the generated secret immediately.

Secrets are shown once. Store the secret in your backend or gateway environment, not in browser code.

Authorization: Bearer <secret>

3. Create an extractor rule

Open Rules from the sidebar.

Extractor rules tell Meterry how to read your raw JSON and create charge items. A typical LLM event might contain:

{
  "type": "response",
  "provider": "openai",
  "usage": {
    "model": "gpt-4.1",
    "prompt_tokens": 1200,
    "output_tokens": 300
  },
  "meta": {
    "subject_type": "user",
    "user_id": "u_01"
  }
}

For that event shape, you can start with this extractor configuration:

{
  "subject": {
    "default_type": "user",
    "type_path": "$.meta.subject_type",
    "id_path": "$.meta.user_id",
    "required": true
  },
  "dimensions": [
    {
      "name": "provider",
      "path": "$.provider",
      "type": "string",
      "required": true
    },
    {
      "name": "model",
      "path": "$.usage.model",
      "type": "string",
      "required": true
    }
  ],
  "charge_item_extractors": [
    {
      "name": "prompt-tokens",
      "metric": "prompt_tokens",
      "path": "$.usage.prompt_tokens",
      "type": "number",
      "unit": "token",
      "required": true,
      "currency": "USD",
      "unit_price_expr": "dec('2.00')",
      "amount_expr": "dec_mul(dec_div(dec(item['quantity']), dec('1000000')), dec(item['unit_price']))"
    },
    {
      "name": "output-tokens",
      "metric": "output_tokens",
      "path": "$.usage.output_tokens",
      "type": "number",
      "unit": "token",
      "required": true,
      "currency": "USD",
      "unit_price_expr": "dec('8.00')",
      "amount_expr": "dec_mul(dec_div(dec(item['quantity']), dec('1000000')), dec(item['unit_price']))"
    },
    {
      "name": "requests",
      "metric": "requests",
      "quantity_expr": "dec('1')",
      "type": "number",
      "unit": "request",
      "currency": "USD",
      "unit_price_expr": "dec('0.001')",
      "amount_expr": "dec_mul(dec(item['quantity']), dec(item['unit_price']))"
    }
  ]
}

This example reads the subject type and ID from meta.subject_type and meta.user_id, falling back to user only when the type path is absent. It keeps provider and model as dimensions, rates prompt tokens at 2.00 USD per 1M tokens, rates output tokens at 8.00 USD per 1M tokens, and adds one request item for each event.

To understand why each field exists and how Meterry executes it, read Create Rules.

In the rule editor:

Choose Create extractor draft.
Give the rule set a name.
Add configuration JSON manually, select a template, or use Ask assistant.
Create the draft.

4. Use the AI assistant when the raw event shape is known

In the extractor draft sheet, select Ask assistant.

Describe:

where the subject lives, such as meta.user_id;
dimensions to keep, such as provider and model;
metrics to bill, such as input tokens, output tokens, and requests;
prices or units if you want stable metrics rated directly.

Example prompt:

Our events have meta.user_id, provider, usage.model,
usage.prompt_tokens, and usage.output_tokens.
Bill prompt and output tokens per million, and add one request item.

The generated JSON replaces the extractor draft editor. Review it before creating the draft.

5. Test the rule in the UI

In Rules, open Rule test.

Select the extractor draft.
Optionally select a pricing rule set.
Paste a raw event JSON sample.
Select Run test.

The result shows extracted dimensions, charge items, unmatched items, and rated amounts when pricing is available.

Adjust the draft and test again until the output matches your expected billing result.

6. Publish the rule

Draft rules do not affect ingestion until published.

Publishing is the step that promotes a tested draft into the project runtime. It gives Meterry a stable, versioned rule set to use for production ingestion and rating, while keeping unfinished drafts out of production. This separation matters because billing rules change money: test drafts freely, then publish only the version you want the production API to use.

In Rules, find the extractor rule set.
Open Details.
Review the configuration and metadata.
Select Publish.

After publishing, return to Rule test and run the same sample against the published rule set. The Portal can then show a simulated real-reporting action that submits the event into ingestion, so you can verify the production API path, Usage explorer output, and account billing behavior.

Use pricing rule sets only when attached extractor pricing is not enough or you need advanced fallback matching. Read Test and Publish for the full workflow.

7. Add accounts and wallets when you need balance control

If you only need usage analytics and charge item calculation, rules and usage events may be enough.

If you need realtime debit, customer balance, credit limits, or usage limits:

Stay in the project that owns the usage events you want to bill.
Open Accounts.
Create an account for the organization, customer, or workspace.
Open Wallets for that account and create a currency wallet.
Open Subject routing and bind a subject such as user/u_01 to the account.
Add usage controls if you want per-subject limits.

Accounts, wallets, voucher grants, and subject routes are isolated by project. Switching projects changes which balances and routes are visible.

Read Accounts and Wallets and Subject Routes before turning on realtime debit.