Usage upsell

# Not live yet (gaps #2)
curl -X POST "https://api.sb/leaseline.app/campaigns?mode=try" \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"play":"usage-upsell"}'

 1import { $ } from 'startup-builder'
 2
 3return await $.Campaign.create({ play: 'usage-upsell' }, { mode: 'try' })   // dry run on the day-0 Startup, 2026-08-24 · Not live yet, gaps #2

npx startup-builder do Campaign.create --json '{"play":"usage-upsell"}' --try   # Not live yet (gaps #2)

{
  "name": "do",
  "arguments": {
    "code": "return await $.Campaign.create({ play: 'usage-upsell' }, { mode: 'try' })   // dry run on the day-0 Startup, 2026-08-24 · Not live yet, gaps #2",
    "mode": "try"
  }
}

 1{
 2  "type": "https://startupbuilder.dev/errors/refused",
 3  "title": "Refused",
 4  "status": 422,
 5  "detail": "usage-upsell can’t start yet: 1 check fails and 2 warn.",
 6  "checks": [
 7    {
 8      "check": "use-when",
 9      "status": "pass",
10      "observed": "41 Customers, 6 a month pacing past a Limit",
11      "doc": "/plays/usage-upsell#check-use-when",
12      "then": "Metric.query"
13    },
14    {
15  …

curl "https://api.sb/leaseline.app/events?where=name%20in%20(%22Entitlement.checked%22%2C%20%22Offer.subscribed%22%2C%20%22Invoice.billed%22%2C%20%22Message.received%22%2C%20%22Renewal.opened%22%2C%20%22Subscription.switched%22%2C%20%22Page.viewed%22)&limit=1" \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY"

# Not live yet (gaps #7)
curl -X POST "https://api.sb/leaseline.app/triggers/fire?mode=try" \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"like":"event_1204"}'

# Not live yet (gaps #7)
curl "https://api.sb/leaseline.app/decisions?where=on%20%3D%20%22customer_12%22" \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY"

# Not live yet (gaps #7)
curl "https://api.sb/leaseline.app/actions?where=on%20%3D%20%22customer_12%22" \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY"

 1import { $ } from 'startup-builder'
 2
 3const { events: [last] } = await $.Event.list({ where: 'name in ("Entitlement.checked", "Offer.subscribed", "Invoice.billed", "Message.received", "Renewal.opened", "Subscription.switched", "Page.viewed")', limit: 1 })   // { play } compiled to this Play’s Trigger Events
 4const { subject } = await $.Trigger.fire({ like: last.$id }, { mode: 'try' })   // the same Event again, in try mode · Not live yet, gaps #7
 5const { decisions: [decision] } = await $.Decision.list({ where: `on = "${subject}"` })   // what it chose, and why · Not live yet, gaps #7
 6const { actions } = await $.Action.list({ where: `on = "${subject}"` })   // what it did, with its checks · Not live yet, gaps #7
 7return { decision, actions }

npx startup-builder do Event.list --json '{"where":"name in (\"Entitlement.checked\", \"Offer.subscribed\", \"Invoice.billed\", \"Message.received\", \"Renewal.opened\", \"Subscription.switched\", \"Page.viewed\")","limit":1}'
npx startup-builder do Trigger.fire --json '{"like":"event_1204"}' --try   # Not live yet (gaps #7)
npx startup-builder do Decision.list --json '{"where":"on = \"customer_12\""}'   # Not live yet (gaps #7)
npx startup-builder do Action.list --json '{"where":"on = \"customer_12\""}'   # Not live yet (gaps #7)

{
  "name": "do",
  "arguments": {
    "code": "const { events: [last] } = await $.Event.list({ where: 'name in (\"Entitlement.checked\", \"Offer.subscribed\", \"Invoice.billed\", \"Message.received\", \"Renewal.opened\", \"Subscription.switched\", \"Page.viewed\")', limit: 1 })   // { play } compiled to this Play’s Trigger Events\nconst { subject } = await $.Trigger.fire({ like: last.$id }, { mode: 'try' })   // the same Event again, in try mode · Not live yet, gaps #7\nconst { decisions: [decision] } = await $.Decision.list({ where: `on = \"${subject}\"` })   // what it chose, and why · Not live yet, gaps #7\nconst { actions } = await $.Action.list({ where: `on = \"${subject}\"` })   // what it did, with its checks · Not live yet, gaps #7\nreturn { decision, actions }",
    "mode": "try"
  }
}

 1{
 2  "decision": {
 3    "$id": "https://api.sb/leaseline.app/decisions/decision_340",
 4    "$type": "Decision",
 5    "choice": "offer-next-plan",
 6    "reason": "118 units on Pro: $68 of overage this period is more than the $50 step to Team",
 7    "stakes": "low",
 8    "options": [
 9      "offer-next-plan",
10      "show-the-saving",
11      "at-renewal",
12      "to-the-ae",
13      "not-now"
14    ],
15  …

action_2 is the note to Kestrel’s billing owner, held 2 minutes; the in-product notice shows at their next sign-in.

≈ +$650 ARR a month at 6

Worth

20 min week 1, then 5 a week

Your time

$0.04 per note, ~$0.25 a month at 3

Spend

Day 4: first upgrade paid

First signal

10+ Customers on an Offer with a Limit, 3+ a month pacing past it

Use it when

Under 10 Customers: instant-response · no Offer has a Limit: add one (Offer.publish)

Not yet when

Worth’s formula: about +18 upgrades per 100 pacing Customers (Other Startups’ results; no lift of your own yet) × 6 a month × $598 per Pro-to-Team upgrade ≈ +$646. Under First signal: At 6 a month, 90 days can tell only +36 per 100 or more, so your file starts at holdout: 0 and reads before-after.

Start it this weekCopy Anchor Link

npx startup-builder add play usage-upsell   # 1 · writes plays/usage-upsell.mdx (Not live yet, gaps #5)

# 2 · dry run; below, its 422 on 2026-08-24
curl -X POST "https://api.sb/leaseline.app/campaigns?mode=try" \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"play":"usage-upsell"}'

# 3 · keep it, at You approve each one
curl -X POST https://api.sb/leaseline.app/campaigns \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"play":"usage-upsell"}'

# on
curl -X PATCH https://api.sb/leaseline.app/campaigns/usage-upsell \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"endsAt":null}'

# off: no ask sends; the bound answer keeps showing
curl -X PATCH https://api.sb/leaseline.app/campaigns/usage-upsell \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"endsAt":"now"}'

{
  "type": "https://startupbuilder.dev/errors/refused",
  "title": "Refused",
  "status": 422,
  "detail": "usage-upsell can’t start yet: 1 check fails and 2 warn.",
  "checks": [
    {
      "check": "use-when",
      "status": "pass",
      "observed": "41 Customers, 6 a month pacing past a Limit",
      "doc": "/plays/usage-upsell#check-use-when",
      "then": "Metric.query"
    },
    {
      "check": "limit-on-offer",
      "status": "pass",
      "observed": "Leaseline Pro: 50 units",
      "doc": "/plays/usage-upsell#check-limit-on-offer",
      "then": "Offer.publish"
    },
    {
      "check": "billing-connected",
      "status": "fail",
      "doc": "/plays/usage-upsell#check-billing-connected",
      "fix": "Connect Stripe so every charge and Meter reading is live.",
      "then": "Integration.connect"
    },
    {
      "check": "baseline",
      "status": "warn",
      "observed": "1 upgrade of 9 pacing Customers in 90 days",
      "doc": "/plays/usage-upsell#check-baseline",
      "fix": "n 9: it reads before-after, not proof, until volume allows a held-back half.",
      "then": "Metric.query"
    },
    {
      "check": "role-unstaffed",
      "status": "warn",
      "roles": [
        "success-manager",
        "billing-specialist"
      ],
      "owned": 4,
      "doc": "/plays/usage-upsell#check-role-unstaffed",
      "fix": "Staff the CSM, or leave it: 4 Customers Priya owns get drafts in her queue.",
      "then": "Role.staff"
    }
  ]
}

Each note costs $0.04 from your Domain (Worker cost), and Meter reads and POST /{namespace}/entitlements/check cost nothing. That comes to about $0.25 a month at 3 pacing Customers and $0.50 at 6.

When it startsCopy Anchor Link

{
  "$id": "https://api.sb/leaseline.app/events/event_1204",
  "$type": "Event",
  "name": "Entitlement.checked",
  "at": "2026-10-19T09:41:12Z",
  "seq": 1204,
  "data": {
    "customer": "customer_12",
    "limit": "units",
    "used": 118,
    "bound": 50,
    "atBound": "overage",
    "resets": "2026-11-01"
  }
}

npx startup-builder trigger Entitlement.checked --like event_1204   # replays the delivery
npx startup-builder clock advance --by 3d   # then runs the day-3 note step
npx startup-builder listen Entitlement.checked --forward-to http://localhost:3000/hook

Who runs itCopy Anchor Link

CSM · your agent (role:success-manager, worker_5) holds the Key Result. It hands to each Customer’s owner: AE · Priya Shah (person) for the 4 she owns and for every Quote over 150 units, and you (Dana Okafor, person) for the rest, because the CSM and Billing Specialist Roles have no person. Your number links to Did it work.

What it reads · What it may call. It reads the Meter, the Entitlement and the live Price, and never a pricing-Page visit or a health score in what it writes. POST /{namespace}/subscriptions/{subscription}/switch is the Customer’s own press, never the agent’s call. Its tools are POST /{namespace}/entitlements/check, POST /{namespace}/messages/{message}/schedule, POST /{namespace}/conversations/{conversation}/answer, POST /{namespace}/conversations/{conversation}/escalate, POST /{namespace}/quotes/{quote}/send, POST /{namespace}/tasks/{task}/assign, and any other call becomes an Approval under the Role’s Mandate.

You hold the CSM Key Result: $3,000 limit upgrade ARR by 2026-12-31.             ← worker, metric
On each Trigger, choose one option and say why; a held Customer gets Not now.    ← triggers, chooses, keep-first
Every number comes from the headroom card, with its as-of time.                  ← copyRules 1
Suggest the upgrade only when it costs less than the overage it replaces.        ← copyRules 3, your file line 4
The switch down sits on the same billing Page, one press away.                   ← copyRules 8

The slow loop. The weekly Decisions kept the $50 step as the line, and no Change was merged in the window, so there is no replay or read-back to print.

What it can do nextCopy Anchor Link

When it hands to youCopy Anchor Link

On this Play, hand-offs go to the Customer’s owner, the CSM’s seat. One Brief per Role, as captured (brief is Not live yet, gaps #7).

[
  {
    "$id": "https://api.sb/leaseline.app/tasks/task_402",
    "$type": "Task",
    "assignee": "worker_3",
    "due": "2026-10-08T11:40:00Z",
    "on": "customer_7",
    "brief": {
      "who": "Birchway Properties, on the $2,400 plan",
      "said": "We’re adding 2 owners: about 420 units by January.",
      "chose": "to-the-ae",
      "why": "over 150 units; a Quote is the AE’s",
      "never": [
        "a discount",
        "a deadline that isn’t real"
      ]
    }
  },
  {
    "$id": "https://api.sb/leaseline.app/tasks/task_388",
    "$type": "Task",
    "assignee": "worker_1",
    "due": "2026-10-03T17:00:00Z",
    "on": "customer_19",
    "brief": {
      "who": "Harbor Row",
      "chose": "not-now",
      "why": "at risk since Oct 2: 3 support threads on late notices",
      "held": "keep-first"
    }
  }
]

The owner answers with POST /{namespace}/tasks/{task}/claim (Take this one), POST /{namespace}/tasks/{task}/return with a reason, or POST /{namespace}/actions/{action}/redirect, each a one-call window. Once a person claims, the agent’s pending asks to that Customer cancel with claimedByPerson (Not live yet, gaps #7), and every reply goes to the owner. A Task nobody claims by its due time goes up a Role through POST /{namespace}/tasks/{task}/escalate, and person-promise fires.

On time: 3 of 3 claimed within their due time, median 40 min, n 3, ■□□□ Too early to tell beside Other Startups’ 94 % on time. Your queue: in week 1, 6 approvals and 1 hand-off; after the promotion, about 1 hand-off a week.

The fixed line: POST /{namespace}/deals/{deal}/assign sets owner to the receiving person, the agent is never a Deal’s owner, and Meetings land on the owner’s calendar under the owner’s name.

When it won’t sendCopy Anchor Link

The captured refusal, then the Stop that fired as a Campaign.paused reason (Not live yet, gaps #2); the rewrite that sent is the Maple Court thread in Example.

{
  "type": "https://startupbuilder.dev/errors/refused",
  "title": "Refused",
  "status": 422,
  "detail": "The note to Harbor Row did not send: they are at risk.",
  "checks": [
    {
      "check": "keep-first",
      "status": "fail",
      "doc": "/plays/usage-upsell#check-keep-first",
      "fix": "Let their CSM reach them first, then ask again once they are healthy.",
      "then": "Task.next"
    }
  ]
}

[
  {
    "reason": {
      "limit": "meter-gap",
      "observed": "3.4 %",
      "bound": "1 %",
      "window": "1 sync"
    },
    "doc": "/plays/usage-upsell#stop-meter-gap",
    "task": "task_351"
  }
]

Did it workCopy Anchor Link

At 6 pacing Customers a month, no held-back half reads within 90 days, so the basis is before-after (rule o): the columns read Now and Before, and nothing prints as Added. Each figure’s call is POST /{namespace}/metrics/query by node, and every node above the leaf is Not live yet (gaps #4).

{
  "$id": "decisions/decision_340",
  "$type": "Decision",
  "choice": "offer-next-plan",
  "reason": "118 units on Pro: $68 of overage this period is more than the $50 step to Team",
  "stakes": "low",
  "options": [
    "offer-next-plan",
    "show-the-saving",
    "at-renewal",
    "to-the-ae",
    "not-now"
  ],
  "by": "worker_5",
  "on": "customer_12",
  "expected": "Subscription.switched to Team within 30d",
  "reopensWhen": "no Subscription.switched for customer_12 within 30d"
}

Before against after reads one window against the 90 days before it, scaled to 56 days; it is not proof, and Other Startups’ results print beside it.

How it moves it: each note names Team’s live Price, today’s prorated charge ($20.00 for Kestrel) and the overage it replaces.

Guardrails: before against after: logo-churn, 0 of 5 upgraded Customers gone against a trailing 2.1 % a month, and contraction-arr, $0 from switches down against $347 before; 3 upgrades are still inside their 90 days, still deciding.

{
  "$id": "https://api.sb/leaseline.app/campaigns/usage-upsell",
  "$type": "Campaign",
  "play": "play:usage-upsell@1",
  "path": [
    "limit-upgrade-arr",
    "expansion-arr",
    "net-new-arr",
    "arr"
  ],
  "experiment": {
    "metric": "limit-upgrade-arr",
    "unit": "usd",
    "heldBack": 0,
    "decision": null
  },
  "readout": {
    "value": null,
    "n": 9,
    "maturing": 2,
    "interval": null,
    "readability": "inadmissible",
    "basis": "before-after",
    "pooled": true
  },
  "ledger": {
    "spend": 1,
    "workerCost": 1,
    "hours": 0.9,
    "pipelineArr": 2400,
    "wonArr": 2990,
    "projectedArr": 646,
    "paybackDays": 1
  }
}

Outside benchmark: 0.75 % of Subscriptions move to a higher Offer in their first month (10.5M purchases at 4,029 companies, a subscription-analytics firm’s billing data, 2026-09-30).

Before it · After it. Before it: instant-response and product-led feed it the trials that convert (Offer.subscribed). After it: annual-prepay hears steady-usage after 3 periods on Team, and customer-referrals hears the Customers it upgraded; keep-first holds both while a Customer is at risk.

ExampleCopy Anchor Link

Leaseline ran it from 2026-08-24 to 2026-10-19 (56 days): 13 Decisions on 11 Customers, 9 of them matured past their 30-day window. Read every captured thread at ?threads=all; three follow the tables.

Leaseline → Kestrel’s billing owner, Oct 19, 09:44 · You’re at 118 units on Pro, 68 past its 50-unit Limit, so this period’s overage is $68.¹ Team is $79 a month for up to 150 units: $20.00 today, then $79 a month, and your overage stops.² Switch with one press; switching back sits on the same page.³ *Signed with the Role’s disclosure line.*⁴

Kestrel, Oct 19, 10:02 · pressed Switch to Team. Subscription.switched, +$598 ARR.

- Upgrade this week and we’ll lock Team at $59 a month.
+ At 56 units, staying on Pro costs $6 in overage this period, less than the $50 step to Team, so staying is cheaper.

Birchway Properties, 2026-10-08 10:40 · “We’re adding 2 owners: about 420 units by January.” · Leaseline, 10:42 · *Thanks. Priya, your account lead, will reply by 11:40 with a Quote.*⁵ The Brief went to Priya (task_402).

¹ Every number comes from the headroom card, as of 09:41. ² The live Price and today’s prorated charge. ³ The switch down, one press away. ⁴ The fixed signature line, compiled from the Role’s disclosure Setting. ⁵ The routed line, compiled from the Role’s Settings.

Your settingsCopy Anchor Link

---
holdout: 0        # 6 a month is too few to hold half back; it reads before-after
---
Offer Team when overage passes the $50 step; under that, show them staying is cheaper. Over 150 units, bring in the AE.

$ npx startup-builder show plays/usage-upsell
holdout 0 · step $50 · AE over 150 units     your file  plays/usage-upsell.mdx:2,4 (Ask 2026-08-24)
family expansion · worker role:success-manager, owns never · chooses 5 (3 rule, 2 read) · sequences usage-upgrade-note, overage-savings-note, usage-upgrade-confirm · checks owned-by-a-person, keep-first, customer-ask-cap, reconcile · stops 11 · placements gmail, outlook + in-product notice    catalog  play:usage-upsell@1 (Not live yet, gaps #5)

Every key from the catalogCopy Anchor Link

Compiled, not written: edit the Play record usage-upsell and its Leaseline run, then regenerate. Every step runs from a sentence or a line of code. In your words: the CRM words you know, and where each lives here.