Owostack
SDK Reference

customer()

Create, resolve, look up, list, and configure customers

customer()

Use owo.customer() to create or resolve a customer by email or ID. The response includes the customer's current billing configuration, and the same namespace exposes helpers for customer-specific billing controls.

For the dedicated guide covering customer-level billing overrides, precedence, and recommended usage, see Customer Config.

For customer-facing usage charts and usage dashboards, the same namespace also exposes usageHistory().

Every read on this namespace (get(), usageHistory(), and the setters) accepts the same identifier you use in track() / check(): your own external customer ID, the customer's email, or the internal Owostack ID.

Signature

const customer = await owo.customer({
  id?: string,         // Optional: Your customer ID
  email: string,       // Required: Customer email
  name?: string,       // Optional: Display name
  metadata?: Record<string, unknown>, // Optional: Custom data
});

const customer = await owo.customer.get(customer: string);

const page = await owo.customer.list({
  limit?: number,      // 1-100, default 50
  offset?: number,     // default 0
  search?: string,     // substring match on email, name, externalId
  email?: string,      // exact (case-insensitive)
  externalId?: string, // exact
});

await owo.customer.setFeatureConfig({
  customer: string,
  feature: string,
  overage?: "block" | "charge" | null,
  maxOverageUnits?: number | null,
});

await owo.customer.setOverageLimit({
  customer: string,
  maxOverageAmount: number | null,
  onLimitReached?: "block" | "notify",
});

await owo.customer.usageHistory({
  customer: string,
  range?: "7d" | "30d" | "90d" | "custom",
  granularity?: "day" | "week" | "month",
  feature?: string | null,
  groupBy?: "total" | "feature",
  timezone?: string,
  from?: string,
  to?: string,
});

Parameters

owo.customer(params)

ParameterTypeRequiredDescription
idstring-Your internal customer ID
emailstring✅Customer email address
namestring-Customer display name
metadataobject-Custom key-value data

owo.customer.get(customer)

ParameterTypeRequiredDescription
customerstring✅External customer ID (what you pass to track), email, or internal ID

Returns the same CustomerResult as owo.customer(). Throws OwostackError with Customer not found when nothing matches within your organization.

owo.customer.list(params?)

ParameterTypeRequiredDescription
limitnumber-Page size, 1–100. Defaults to 50.
offsetnumber-Customers to skip. Defaults to 0.
searchstring-Case-insensitive substring match on email, name and external ID
emailstring-Exact email match (case-insensitive)
externalIdstring-Exact external ID match

Results are newest first. total is the number of customers matching the filters, so offset + data.length < total means there is another page.

owo.customer.setFeatureConfig(params)

ParameterTypeRequiredDescription
customerstring✅Customer ID or identifier
featurestring✅Feature slug or ID
overage"block" | "charge" | null-Override overage behavior for this feature
maxOverageUnitsnumber | null-Override the hard overage cap for this feature

Provide at least one of overage or maxOverageUnits. Pass null to clear an existing override.

owo.customer.setOverageLimit(params)

ParameterTypeRequiredDescription
customerstring✅Customer ID or identifier
maxOverageAmountnumber | null✅Customer-wide spend cap in minor units
onLimitReached"block" | "notify"-Behavior when the spend cap is reached. Defaults to block

Pass null for maxOverageAmount to remove the spend cap.

owo.customer.usageHistory(params)

ParameterTypeRequiredDescription
customerstring✅Customer ID
range"7d" | "30d" | "90d" | "custom"-Preset range or custom window. Defaults to 30d.
granularity"day" | "week" | "month"-Bucket size for aggregation. Defaults to day.
featurestring | null-Optional feature slug or ID to filter to one feature.
groupBy"total" | "feature"-Return only the total series or include per-feature breakdowns. Defaults to total.
timezonestring-IANA timezone used for bucket boundaries. Defaults to UTC.
fromstring-Inclusive YYYY-MM-DD start date when range is custom.
tostring-Inclusive YYYY-MM-DD end date when range is custom.

Use usageHistory() when you want chart-friendly usage buckets.

Use owo.billing.usage() when you want uninvoiced overage and estimated billable amounts.

Returns

owo.customer(), get(), setFeatureConfig(), and setOverageLimit() all return the customer plus the current customer billing config.

interface CustomerResult {
  id: string;                 // Internal Owostack ID
  externalId: string | null;  // Your ID (the `customer` value you track with)
  email: string;
  name?: string | null;
  metadata?: Record<string, unknown> | null;
  billing: {
    overageLimit: {
      maxOverageAmount: number | null;
      onLimitReached: "block" | "notify";
      createdAt: number;
      updatedAt: number;
    } | null;
    featureConfigs: Array<{
      feature: {
        id: string;
        slug: string | null;
        name: string;
      };
      overage: "block" | "charge" | null;
      maxOverageUnits: number | null;
      createdAt: number;
      updatedAt: number;
    }>;
  };
  createdAt: number;
  updatedAt: number;
}

owo.customer.list() returns a page of lightweight customer summaries (no billing config):

interface CustomerListResult {
  success: true;
  data: Array<{
    id: string;
    externalId: string | null;
    email: string;
    name: string | null;
    metadata: Record<string, unknown> | null;
    createdAt: number;
    updatedAt: number;
  }>;
  total: number;
  limit: number;
  offset: number;
}

owo.customer.usageHistory() returns aggregated usage history:

interface UsageHistoryResult {
  customer: {
    id: string;
  };
  query: {
    range: {
      from: string;
      to: string;
    };
    granularity: "day" | "week" | "month";
    feature: string | null;
    groupBy: "total" | "feature";
    timezone: string;
  };
  totals: {
    usage: number;
    records: number;
  };
  series: Array<{
    bucket: string;
    value: number;
  }>;
  breakdown: Array<{
    feature: {
      id: string;
      slug: string | null;
      name: string;
      unit: string | null;
    };
    totals: {
      usage: number;
      records: number;
    };
    series: Array<{
      bucket: string;
      value: number;
    }>;
  }>;
}

Examples

Create or Resolve a Customer

import { Owostack } from "owostack";

const owo = new Owostack({ secretKey: process.env.OWOSTACK_API_KEY });

// Create an org customer
const org = await owo.customer({
  email: "billing@acme.com",
  name: "Acme Corporation",
  metadata: { industry: "SaaS" },
});

console.log(org.id);
console.log(org.billing.overageLimit); // null by default
console.log(org.billing.featureConfigs); // []

Resolve an Existing Customer

// Resolve existing customer by email
const existing = await owo.customer({
  email: "billing@acme.com",
});

// Or by your internal ID
const byId = await owo.customer({
  id: "org_acme",
  email: "billing@acme.com",
});

Look Up a Customer by Your Own ID

// The id you pass to track()/check() works for reads too
await owo.track({ customer: "workspace_alpha", feature: "agent_turns" });

const customer = await owo.customer.get("workspace_alpha");
console.log(customer.id);         // internal UUID
console.log(customer.externalId); // "workspace_alpha"

// Email works as well
const byEmail = await owo.customer.get("billing@acme.com");

List and Search Customers

// First page, newest first
const page = await owo.customer.list({ limit: 25 });

// Search across email, name and external id
const matches = await owo.customer.list({ search: "acme" });

// Exact lookups
const { data } = await owo.customer.list({ externalId: "workspace_alpha" });

// Walk every page
for (let offset = 0; ; offset += 100) {
  const { data, total } = await owo.customer.list({ limit: 100, offset });
  for (const customer of data) console.log(customer.externalId ?? customer.email);
  if (offset + data.length >= total) break;
}

Set a Per-Feature Overage Policy

const updated = await owo.customer.setFeatureConfig({
  customer: "cust_123",
  feature: "api_calls",
  overage: "block",
  maxOverageUnits: 1000,
});

console.log(updated.billing.featureConfigs);

Set a Customer-Wide Overage Spend Cap

const updated = await owo.customer.setOverageLimit({
  customer: "cust_123",
  maxOverageAmount: 500_000,
  onLimitReached: "block",
});

console.log(updated.billing.overageLimit);

Clear Customer Billing Overrides

await owo.customer.setFeatureConfig({
  customer: "cust_123",
  feature: "api_calls",
  overage: null,
  maxOverageUnits: null,
});

await owo.customer.setOverageLimit({
  customer: "cust_123",
  maxOverageAmount: null,
  onLimitReached: "block",
});

Get Aggregate Usage History

const history = await owo.customer.usageHistory({
  customer: "cust_123",
  range: "30d",
  granularity: "day",
  groupBy: "total",
  timezone: "Africa/Lagos",
});

console.log(history.totals.usage);
console.log(history.series);

Get Per-Feature Usage History

const history = await owo.customer.usageHistory({
  customer: "cust_123",
  range: "90d",
  granularity: "week",
  groupBy: "feature",
});

for (const feature of history.breakdown) {
  console.log(feature.feature.slug, feature.totals.usage);
}

Use a Custom Date Window

const history = await owo.customer.usageHistory({
  customer: "cust_123",
  range: "custom",
  granularity: "day",
  from: "2026-04-01",
  to: "2026-04-30",
});

Using the Customer Object

The returned customer object has convenience methods:

const org = await owo.customer({ email: "org@acme.com" });

// Attach subscription
await org.attach({ product: "team" });

// Manage entities (seats)
await org.addEntity({
  feature: "seats",
  entity: "user_123",
  name: "John Doe",
});

const { entities } = await org.listEntities({ feature: "seats" });

Entity Management Methods

Customer objects provide these entity management methods:

customer.addEntity(params)

Add an entity (e.g., seat) to the customer.

await org.addEntity({
  feature: "seats",
  entity: "user_123",
  name: "John Doe",
  email: "john@acme.com",
  metadata: { role: "admin" },
});

Parameters:

  • feature (string, required): Feature slug
  • entity (string, required): Your entity ID
  • name (string, optional): Display name
  • email (string, optional): Contact email
  • metadata (object, optional): Custom data

customer.removeEntity(params)

Remove an entity and free up the slot.

await org.removeEntity({
  feature: "seats",
  entity: "user_123",
});

customer.listEntities(params?)

List entities for this customer.

// List all entities
const { entities } = await org.listEntities();

// Filter by feature
const { entities: seats } = await org.listEntities({ feature: "seats" });

Best Practices

  1. Create early - Create the customer before attaching subscriptions or adding entities
  2. Use consistent IDs - Either always pass your own id or always use email as identifier
  3. Store metadata - Use metadata for customer segmentation and analytics
  4. Use spend caps as safety rails - setOverageLimit() protects the whole customer across billable overage
  5. Use feature config for exceptions - setFeatureConfig() is best for one risky or contract-specific feature
  6. Use usageHistory for charts - usageHistory() is for usage dashboards, not invoice estimation
  7. Update on changes - Call customer() when user data changes to keep billing records in sync
  • Customer Config - Customer-level billing overrides and spend caps
  • billing - Uninvoiced overage, invoices, and invoice generation
  • attach() - Subscribe customer to a plan
  • Overage - How plan overage and customer overrides interact
  • addEntity() - Add entities/seats (flat API)
  • Seat Pricing Guide - Complete seat-based billing walkthrough

Create plans & features

Reference: metered(), boolean(), entity(), creditSystem(), creditPack(), plan() — define features and plans as code

Customer Config

Customer-level billing controls for feature overage and spend caps

On this page

customer()
Signature
Parameters
owo.customer(params)
owo.customer.get(customer)
owo.customer.list(params?)
owo.customer.setFeatureConfig(params)
owo.customer.setOverageLimit(params)
owo.customer.usageHistory(params)
Returns
Examples
Create or Resolve a Customer
Resolve an Existing Customer
Look Up a Customer by Your Own ID
List and Search Customers
Set a Per-Feature Overage Policy
Set a Customer-Wide Overage Spend Cap
Clear Customer Billing Overrides
Get Aggregate Usage History
Get Per-Feature Usage History
Use a Custom Date Window
Using the Customer Object
Entity Management Methods
customer.addEntity(params)
customer.removeEntity(params)
customer.listEntities(params?)
Best Practices
Related

Ask about owostack

Ready

Start a new chat below.

Powered by Cull