---
name: bijection-metering
description: "Evaluate and integrate the Metering component with Bijection."
---

# Metering

Metered usage records — idempotent usage events rolled up per billing period, as a Bijection component

- Package: @bijectionhq/metering
- Category: Payments
- Status: Preview
- License: MIT
- Bijection source (repository access required): https://github.com/bijectionhq/metering/tree/cd6bd628943344281d9e38e2aedd0f6aad0585c6
- Upstream: https://github.com/vllnt/convex-metering/tree/4f43413f1d824c20aa2536aaeeb42bdc6212671d
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/metering

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/metering.git
cd metering
git checkout cd6bd628943344281d9e38e2aedd0f6aad0585c6
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes @vllnt/convex-metering. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses Usage Metering. Follow the installation and configuration steps exactly.

# Usage Metering

## Instructions

@vllnt/convex-metering turns usage events into per-subject, per-period totals. Choose sum, max, or last aggregation and define your own units and period labels, without tying your product to a payment provider.

Define a meter, record quantities with idempotency keys, and read period totals. recordWithLimit checks a cap and records usage in one transaction. adjust corrects sum meters; closePeriod freezes a period. Raw records and a separate deduplication ledger support retention and reconciliation.

Your app verifies usage, supplies billing periods, sets rates, and generates invoices or charges through its provider. The component does not process payments. Deduplication retention and record pruning remain operational choices your backend must manage.

Maintained by [bntvllnt](https://bntvllnt.com) at [VLLNT](https://vllnt.com). Find the author on [GitHub](https://github.com/bntvllnt) and [X](https://x.com/bntvllnt).

### Installation

```bash
npm install @vllnt/convex-metering
```

Current npm version: `@vllnt/convex-metering@0.1.0`

## Use cases

- Developer APIs: total requests or processed units per workspace.
- AI tools: record token counts, generations, or compute units supplied by your backend.
- Storage products: track peak usage or the latest measured storage value.
- Media and data apps: aggregate processing minutes, exports, or completed jobs for reporting or billing.

## How it works

Define a meter, record quantities with idempotency keys, and read period totals. recordWithLimit checks a cap and records usage in one transaction. adjust corrects sum meters; closePeriod freezes a period. Raw records and a separate deduplication ledger support retention and reconciliation.

Your app verifies usage, supplies billing periods, sets rates, and generates invoices or charges through its provider. The component does not process payments. Deduplication retention and record pruning remain operational choices your backend must manage.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Usage Metering is not needed

## Resources

- [npm package](https://www.npmjs.com/package/%40vllnt%2Fconvex-metering)
- [GitHub repository](https://github.com/vllnt/convex-metering)
- [Live demo](https://vllnt.com/)
- [Convex Components Directory](https://www.convex.dev/components/vllnt/convex-metering)
- [Convex documentation](https://docs.convex.dev)