Benefits
The trials, free plans, credits and offers you protect, and the settings that decide who can claim each one.
A benefit is anything your product gives a user up front or within a limit: a free or paid introductory trial, a free plan, sign-up credits, a referral bonus or a promotional offer. In AbuseZero, each benefit is a named configuration, and every evaluation runs against exactly one of them.
Why benefits are separate
Abuse depends on what is being claimed. A user who already took your trial may still be welcome to claim referral credits. So each benefit keeps its own claim history, its own eligibility window, its own policy and its own automation settings. Protection fits what you give away, benefit by benefit, without one benefit's history blocking another.
Key capabilities
- Full history on every call. Every claim is checked against the benefit's complete claim history, across every identifier you send, on every evaluation.
- Exact eligibility windows. A benefit can be claimed once ever, once per calendar day, week or month in the time zone you choose, or once every set number of days. AbuseZero applies the window to the exact boundary.
- Simultaneous claims. Claims that arrive at the same moment and share identifiers are settled one at a time. Two parallel sign-ups can't both pass as someone's first claim.
- Safe concurrent edits. Every benefit carries a
revision. An update made against an older revision is refused withBENEFIT_CONFLICT, so one teammate's change never silently overwrites another's. - Versioned decisions. Policy changes apply to future evaluations only. Each evaluation records the exact policy version it ran under.
Configuration
| Setting | Field | Values |
|---|---|---|
| Name | name | Up to 80 characters. Shown in the dashboard. |
| Key | key | Lowercase letters, digits and underscores, starting with a letter, up to 64 characters. You send it as benefit in each evaluation. It is set when the benefit is created and doesn't change. |
| Protection | policy_key | lenient, balanced, strict, or the key of one of your custom policies. See Protection levels. |
| Mode | protection_mode | protect or observe. |
| Eligibility | config.eligibility | How often one user can receive the benefit. Set when the benefit is created. To change it, create a new benefit. |
| Delivery confirmation | config.outcome_tracking | assume_granted or report_outcome. See Outcomes. |
| If delivery isn't confirmed | config.missing_outcome_behavior | hold_eligibility or release_eligibility. |
| Automated traffic | config.automation | assess, deny or allow. See Bots and AI agents. |
| Automation check | config.bot_evidence | optional or required. |
| Verified AI agents | config.allowed_agents | Agent IDs from GET /v1/agents. |
| Valuation | config.valuation | currency, face_value and delivery_cost. Used for reporting only. It never changes an evaluation. |
Protect and observe
- Protect returns your policy's result.
- Observe always returns
allowand records what the policy would have decided. The evaluation shows that asobserved_result.
Start a new benefit in observe mode to measure how much repeat claiming it attracts before you act on it. Then switch to protect. Your integration code stays the same.
Eligibility
{ "kind": "once" }{ "kind": "calendar", "period": "month", "timezone": "Europe/Berlin" }{ "kind": "rolling", "days": 30 }period is day, week or month, and timezone is a time zone name such as Europe/Berlin. days is a whole number from 1 to 365.
Valuation
Valuation records what a user receives (face_value) and what the benefit costs you to deliver (delivery_cost), in one three-letter currency. Analytics in the dashboard totals these per currency.
Programmatic access
| Interface | Use |
|---|---|
| AbuseZero REST API | POST /v1/benefits, GET /v1/benefits, GET /v1/benefits/{id}, PATCH /v1/benefits/{id}, DELETE /v1/benefits/{id} |
| AbuseZero Node.js SDK | createBenefit(), benefits(), getBenefit(), updateBenefit(), deleteBenefit() |
| AbuseZero CLI | abusezero benefits create, list, get, update, delete |
| AbuseZero MCP server | abusezero_create_benefit, abusezero_list_benefits, abusezero_get_benefit, abusezero_update_benefit, abusezero_delete_benefit |
| Dashboard | Benefits |
Response data
{
"object": "benefit",
"id": "ben_8c2f1d64-3a7e-4b19-9f05-2e6d7c1a9b38",
"key": "pro_trial",
"name": "Pro trial",
"policy": "pol_51b9e2a7-0c4d-4f6e-8a13-7d2c9e5f0b14",
"mode": "protect",
"config": {
"eligibility": { "kind": "once" },
"outcome_tracking": "assume_granted",
"missing_outcome_behavior": "hold_eligibility",
"automation": "assess",
"bot_evidence": "optional",
"allowed_agents": [],
"valuation": { "currency": "USD", "face_value": 49, "delivery_cost": 6.5 }
},
"revision": 3,
"created_at": "2026-10-12T09:41:27.000Z"
}Your plan sets how many benefits a workspace can have. When a workspace is over its plan's limits, evaluations for a paused benefit return status: "skipped" with the reason benefit_paused. Workspace owners manage plans in Workspace settings → Billing & Subscriptions.
Next steps
How is this guide?
Last updated on