The Usage module object

A usage module joins two objects: the one holding what you sell and the one holding who consumes it. Your application records consumption against it; Custral stores the events on the product and customer records.

{
  "id": "umod_3Ab9xK2mQ7",
  "name": "Compression",
  "productObjectId": "obj_3Ab9xK2mQ7",
  "customerObjectId": "obj_5Bc0xJ1kP4",
  "productIdentifierPropertyId": null,
  "customerIdentifierPropertyId": "prop_7Dd2xL3nR6",
  "createdAt": "2026-01-02T03:04:05.000Z"
}

Attributes

string

Unique identifier, prefixed umod_.

string | null

What this metered product is called.

string | null

The object holding the things being sold.

string | null

The object holding the people who consume them.

string | null

Optional property an external system identifies products by: a SKU, say.

string | null

Optional property an external system identifies customers by.

string | null

ISO 8601 timestamp.

Two keys, on purpose

Recording usage and reading it back need different keys, and the split is deliberate:

	Endpoint	Key
Record an event	`POST /usage/track`	publishable (`pk_…`)
Read events back	`GET /v1/usage-modules/{id}/events`	secret (`sk_…`) + `usage:read`

track takes a publishable key so it can be called straight from a browser at the moment of consumption. Reading events back is not publishable. A client-side key must never be able to enumerate a workspace’s usage.

Recording usage

Use @custral/js from your app:

import {CustralUsage} from "@custral/js";

const usage = new CustralUsage({key: "pk_...", moduleId: "umod_..."});

await usage.track({
  productRecordId: "rec_...",
  customerRecordId: "rec_...",
  quantity: 5,
});

Reading it back

With the server SDK, holding usage:read:

const events = await custral.usageModules.listEvents("umod_...", {
  customerRecordId: "rec_...",
  from: "2026-01-01T00:00:00.000Z",
});

Events come back newest first, 50 to a call. That is the one list in the API whose length is set by your own application rather than by anything a person does in the workspace, so it always pages. A call without limit is a page, not the history.

integer

Page size, 1–200. Defaults to 50.

integer

Rows to skip, for the next page.

To total a period, filter it rather than paging to the end:

const january = await custral.usageModules.listEvents("umod_...", {
  customerRecordId: "rec_...",
  from: "2026-01-01T00:00:00.000Z",
  to: "2026-02-01T00:00:00.000Z",
  limit: 200,
});

Introduction

Endpoints

Embeds & real-time

The Usage module object

Attributes

Two keys, on purpose

Recording usage

Reading it back

​Attributes

​Two keys, on purpose

​Recording usage

​Reading it back

Attributes

Two keys, on purpose

Recording usage

Reading it back