Subscription + overage
Charge a base fee with included usage, then bill each additional unit.
Charge a base fee with included usage, then bill each additional unit.
Sell Quillby for $29/month with a recurring usage allowance and per-word overage. Customers under the allowance pay the base fee; heavier customers pay for the extra usage.
Use this model when customers want predictable access but their usage varies.
ctx.report()import * as fs from "@farthershore/business";
const words = fs.measure("words");
const usage = fs.meter("word_usage", { measures: [words] });
const usagePricing = fs.pricing("word_usage", {
meter: usage,
catalog: [fs.rate.per(1000, fs.money.usd(0.2))],
});
const api = fs.backend("api", {
default: true,
});
const generate = fs.route("/v1/generate", {
post: { backend: api },
});
const generateStream = fs.route("/v1/generate-stream", {
post: { backend: api },
});
fs.meterRoutes("generated-words", generate, {
reports: [usage],
maxOutputUnits: words.atMost(4_000),
});
fs.meterRoutes("generated-words-stream", generateStream, {
reports: [usage],
postStream: { settlementMax: [words.atMost(4_000)] },
});
fs.plan("author", {
kind: fs.plan.kind.hybrid,
price: fs.money.usd(29).monthly(),
usagePricing: usagePricing.current(),
funding: { buckets: [fs.included(fs.money.usd(10))] },
spendPolicy: {
onExhaustion: fs.exhaustion.overage(usagePricing.current()),
},
maxMonthlySpendCents: 50_000,
});
export default fs.business();
The exact rate prices each word at $0.0002 — 50,000 words per $10 allowance.
The branded words measure guarantees the pricing dimension resolves. The
included bucket pays the first $10 of rated usage every period; the declared
overage policy rates the rest at the same catalog as amount due. The hybrid
kind requires exactly this shape (price, usagePricing, funding,
spendPolicy with exhaustion.overage).
Overage is unbounded by construction, so the plan must also state an upper
bound or the build fails with PLAN_UNBOUNDED_SPEND. maxMonthlySpendCents
caps the subscriber's monthly bill at $500; a rate limit
(limits: [requests.perMinute(600)]) or a blocking policy
(spendPolicy: { onExhaustion: exhaustion.block }, which forgoes overage
entirely) satisfy the same requirement. See
Billing strategies and
Funding & allowances.
Report request-bound usage from the backend:
await ctx.report({
meter: "word_usage",
values: { words: generatedWordCount },
});
For the streaming route, call the same verb after the stream closes:
await ctx.report({
meter: "word_usage",
values: { words: generatedWordCount },
});
Once the response is on the wire, ctx.report() automatically delivers over
the attested post-stream channel; the postStream.settlementMax bound on the
binding tells admission the most that report can be worth. It carries the
served identity of the original request and is billing-only; it does not
retroactively enforce the current request.
farthershore build --format json
farthershore commercial-release diff previous-release.json candidate-release.json --format json
farthershore validate --format json
git add business/ && git commit -m "add Author overage plan" && git push
# After explicit approval of the exact active-business release:
approved_sha="$(git rev-parse HEAD)"
git tag -a v1.2.0 "$approved_sha" -m "v1.2.0"
git push origin v1.2.0
gh release create v1.2.0 --verify-tag --target "$approved_sha" --title "v1.2.0" --generate-notes
farthershore business status quillby --format json
Replace the example version with the approved semantic version. Active
repo-managed businesses publish subsequent versions with GitHub Releases, not
farthershore business publish.
Poll status until ACTIVE and live: true.
farthershore business status quillby --format json reports live: true.POST /v1/generate complete and report words.farthershore usage summary quillby --format json shows words increasing
for both below-allowance and above-allowance tests.consumedNanos rising to $10, then receivableNanos growing at exactly
$0.0002 per word.| Symptom | Fix |
|---|---|
| No usage appears | Match the fs.meter() key and measure key exactly; report through ctx.report(). |
| Wrong amount | Read the bill preview; confirm the catalog rate and the included amount in the release. |
| Duplicate usage | Reuse the request identity; request-bound callbacks are idempotent. |
| Unexpected denial | Inspect the rate/quota response metadata and usage summary. |
Correct meter or plan values in business/ and publish a new version. A
catalog change reaches current()-bound subscribers from activation forward;
a recurring-price change reaches new subscriptions only.
Add a words meter and an Author plan to Quillby: $29/month, included funding,
and $0.0002 per word overage. Report request-bound usage through an attested SDK
channel. Build and verify in preview, then show the exact commit, semantic diff,
and proposed GitHub Release and ask for approval. After approval, release and
verify low- and high-usage calls. Do not use unattested background metering for
request-bound usage.