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

Optional object holding the people inside a customer account (Contacts, say). An event’s user is matched to a record of this object.

string | null

Optional property on the actor object that an event’s user is matched against: an email, say.

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,
});

// A named event, with the person who did it. No product needed.
await usage.track({
  event: "report_created",
  customerRecordId: "acct_42",
  user: "jane@acme.com",
});

Every event needs a customer, and either a product or an event name. user is optional. customerRecordId, productRecordId and user each accept a Custral record id, or a value of the module’s identifier property on that side (your own account id, a SKU, an email).

Identifiers that match no record

If an identifier matches no record, the event is still stored, but it counts toward no record’s usage. track tells you which side missed:

{"success": true, "id": "uevt_...", "unmatched": ["customer"]}

The event keeps the value you sent as customerKey / productKey. It is never stored as a record id. To see what is waiting and under which keys:

const unmatched = await custral.usageModules.listUnmatched("umod_...");
// {events: 38, customerKeys: 1, productKeys: 0,
//  keys: [{side: "customer", key: "acct_42", events: 38, quantity: 38, lastSeenAt: "..."}]}

GET /v1/usage-modules/{id}/unmatched needs usage:read. Later events with that key start matching once a record carries it in the module’s identifier property.

Reading it back

With the server SDK, holding usage:read:

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

Each event carries event, actorRecordId / actorKey (who did it), and customerKey / productKey when that side matched no record. Filter by event to read one kind of event. 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,
});

Usage per record

Two reads answer the questions a usage table is usually built for, already totalled. They are the same figures the Usage by customer and Usage by product blocks show.

Record	Endpoint	Answers
A product	`GET /v1/records/{object}/{id}/usage/by-customer`	Who uses this product, how much, and who is slipping
A customer	`GET /v1/records/{object}/{id}/usage/by-product`	How this customer uses each product

Both need a secret key with usage:read and records:read. The response names records, and usage:read on its own never reveals a record’s name. You don’t pass a module. It is found from the record’s object: the module whose product object (for by-customer) or customer object (for by-product) that record belongs to. When several modules meter the object, the oldest is read, every one is listed in modules, and moduleId picks another. breakdown is null when no module meters the object on that side, for example a customer record passed to by-customer.

string

Query parameter. The usage module (umod_…) to read, when several meter the record’s object.

Usage by customer

const {modules, breakdown} = await custral.records.usageByCustomer({
  object: "products",
  id: "rec_...",
});

{
  "modules": [{"id": "umod_3Ab9xK2mQ7", "name": "Product usage"}],
  "moduleId": "umod_3Ab9xK2mQ7",
  "breakdown": {
    "windowDays": 30,
    "customersUsing": 12,
    "activeCustomers": 40,
    "uses": 3000,
    "previousUses": 3410,
    "changePercent": -12,
    "usesAllTime": 612940,
    "firstUsedAt": "2026-01-12T09:00:00.000Z",
    "weeks": [{"start": "2026-06-23", "uses": 80}],
    "topCustomers": [{"recordId": "rec_5Bc0xJ1kP4", "name": "Kestrel Logistics", "uses": 900}],
    "slipping": [
      {"recordId": "rec_7Dd2xL3nR6", "name": "Harbor & Pine", "previous": 400, "recent": 0, "percent": 100}
    ],
    "neverTried": {
      "count": 2,
      "examples": [{"recordId": "rec_9Ee4xM5pS8", "name": "Brightline Dental"}]
    }
  }
}

Field	Counted as
`uses`	The sum of each event’s `quantity` in the last `windowDays` (30) days.
`previousUses`, `changePercent`	The 30 days before that. `changePercent` is `null` when they had no uses.
`customersUsing`	Customers with a use of this product in the window.
`activeCustomers`	Customers with a use of any product in the module in the window.
`weeks`	12 seven-day buckets of whole UTC days, oldest first. The last one ends today.
`topCustomers`	Up to 5, most uses in the window first.
`slipping`	Up to 5. Last 14 days down at least 30% on the 14 before, with at least 10 uses and 3 events in the earlier window. `percent` is 100 when they stopped.
`neverTried`	`count` of active customers with no use of this product, ever, and up to 3 `examples`.

Usage by product

const {breakdown} = await custral.records.usageByProduct({
  object: "companies",
  id: "rec_...",
});

{
  "modules": [{"id": "umod_3Ab9xK2mQ7", "name": "Product usage"}],
  "moduleId": "umod_3Ab9xK2mQ7",
  "breakdown": {
    "windowDays": 30,
    "uses": 900,
    "previousUses": 0,
    "changePercent": null,
    "productsUsed": 1,
    "productsTotal": 30,
    "weekStarts": ["2026-06-23"],
    "products": [
      {
        "recordId": "rec_2Aa1xK9mQ3",
        "name": "Payroll",
        "uses": 900,
        "previousUses": 0,
        "changePercent": null,
        "slippingPercent": null,
        "lastUsedAt": "2026-09-14T10:00:00.000Z",
        "weeks": [900]
      }
    ],
    "moreNotUsed": 27
  }
}

products lists products in use first, most used first, and never cuts them. Products this customer did not use fill the rest, up to 25 rows, most recently used first; moreNotUsed counts the ones left out. Each row’s weeks lines up with weekStarts, and slippingPercent uses the same 14-day rule as slipping above, for this customer on this product.

Names and what you can read

Counts cover every customer. The named lists (topCustomers, slipping, neverTried.examples and products) only include records the key can read, so a private account is counted but not named. A record with no usable name comes back with name: "", never its id. Show your own placeholder. A record that doesn’t exist, or that the key can’t read, is not_found, and so is a record that isn’t in {object}.

Introduction

Endpoints

Embeds & real-time

The Usage module object

Attributes

Two keys, on purpose

Recording usage

Identifiers that match no record

Reading it back

Usage per record

Usage by customer

Usage by product

Names and what you can read

​Attributes

​Two keys, on purpose

​Recording usage

​Identifiers that match no record

​Reading it back

​Usage per record

​Usage by customer

​Usage by product

​Names and what you can read

Attributes

Two keys, on purpose

Recording usage

Identifiers that match no record

Reading it back

Usage per record

Usage by customer

Usage by product

Names and what you can read