Bonuses are one-time additional usage amounts for a customer and feature.
Use bonuses for:
- Service recovery credits
- Promotional credits
- Manual goodwill adjustments
How bonuses work
Bonuses are attached to a specific:
Bonuses can also include:
expiresAtreasonmetadata
When you evaluate feature access, bonus data is included on tracked limit features:
Bonuses are for tracked limit features. Boolean features do not use bonus counters.
Create a bonus
Use bonuses.create to grant extra usage to a customer.
const result = await priceos.bonuses.create({
customerId: "customer_123",
featureKey: "api_calls",
amount: 100,
expiresAt: Date.parse("2026-12-31T23:59:59.000Z"),
reason: "promotion",
metadata: {
campaign: "winter_promo",
},
});
bonusIdremainingAmount (for this bonus)counterRemaining (total for this customer + feature)
List bonuses
const { bonuses } = await priceos.bonuses.list({
customerId: "customer_123",
featureKey: "api_calls",
});
Update a bonus
You can change amount, expiry, reason, or metadata for a bonus.
const result = await priceos.bonuses.update({
bonusId: "9e9be7e5-55d2-4b44-93af-c3687f4b8af5",
amount: 150,
expiresAt: null, // clear expiration
reason: "manual_adjustment",
});
Delete a bonus
Delete removes a bonus grant that has not been consumed.
const result = await priceos.bonuses.delete("9e9be7e5-55d2-4b44-93af-c3687f4b8af5");
Read bonus usage in feature access
import { PriceOS } from "priceos";
import type { MyFeatures } from "./priceos.types";
const priceos = new PriceOS<MyFeatures>(process.env.PRICEOS_API_KEY!);
const access = await priceos.features.getAccess("customer_123");
const apiCalls = access.api_calls;
const bonusRemaining = apiCalls.usage.bonusRemaining;
const bonusUsed = apiCalls.usage.bonusUsed;
Next Steps
