Skip to main content

Campaigns

A Grant Campaign is a reusable, event-driven operational activity. Integrations record business facts through Billing Events; a Campaign matches those facts and directly creates Grant Assignments for its configured reward bundle.

Billing Event means an event recorded inside the Billing system, not an event that must itself be related to charging. User activity such as signup and invitation acceptance can share the same append-only event log with outcome events. Event-to-Ratings and Campaigns consume that log independently.

Campaigns never scan existing Billing Accounts or Billing Users, and they do not assign Billing Plans.

Billing Event integration​

Send POST /mgt/v1/events with X-Realm-Id, X-Principal-Id, X-User-Id, and a request-level Idempotency-Key. Every event body also includes an event_key, which defines the developer-chosen uniqueness boundary within the resolved Billing User. The first write wins: later submissions of the same key for that user return the original event without comparing content. Different users may reuse the same key. Batch requests carry one transport key and one event_key per item.

event_type is a developer-managed, case-sensitive string such as user.signup or invitation.accepted. It does not need to be registered. payload is an arbitrarily nested JSON object containing the canonical event facts. Use semantic_kind: activity for events such as signup and invitation acceptance.

The same Billing Event may match Event-to-Ratings and one or more Campaigns. A Campaign does not depend on the rating consumer's processing status.

Campaign configuration​

  • event_type exactly matches the Billing Event type.
  • payload_match is an arbitrarily nested JSON object matched using JSON containment. {} means every actual event of this type, not every user in the database.
  • assignment_trigger: first_match enrolls and rewards a Billing User once. It can bind one-time or periodic Grant Programs.
  • assignment_trigger: every_match creates a reward bundle for every matching event. It can bind only one-time Grant Programs.
  • window_start and window_end determine event eligibility using a half-open interval.
  • metadata.grants contains one or more { grant_program_code, amount_xusd } bindings and is committed as one atomic reward bundle.

Campaigns and Grant Programs are reusable definitions. Your application sends events; it does not create a Campaign for each signup, invitation, or other occurrence.

Lifecycle​

A Campaign moves from scheduled to active, may be paused and resumed, and eventually becomes ended. Trigger, payload match, window, and reward bindings can change only while the Campaign is scheduled. Ending or pausing a Campaign does not revoke assignments or grants already created.

Paused Campaigns retain eligible backlog. Ended Campaigns finish events that were ingested before their ended_at cutoff, including work delayed in the sweep, but reject later ingested backdated events.

Next​