Guide · Events

Server only

Send activity only after your server has verified it.

Events are the evidence entitlement rules evaluate. Our Impact automatically records completed donations from its widget; use the API for trusted activity completed elsewhere.

Automatic versus custom events

Automatic

Hosted PayPal donation

When an identified supporter completes checkout in the campaign widget, Our Impact records donation.completed after PayPal capture succeeds.
SDK

Your own verified activity

If your backend confirms a donation or another supported action elsewhere, send it with client.events.createVerifiedEvent().

Create an event

Use the project secret from a trusted server. The SDK maps camelCase input to the API’s snake_case wire format.

record-donation.ts
import { OurImpactClient } from "@our-impact/node";

const ourImpact = new OurImpactClient({
  secretApiKey: process.env.OUR_IMPACT_SECRET_KEY,
});

const result = await ourImpact.events.createVerifiedEvent({
  body: {
    id: "donation_01JABC123",
    type: "donation.completed",
    externalUserId: "storefront:user_01JABC",
    displayName: "Avery",
    occurredAt: new Date("2026-11-06T12:00:00Z"),
    properties: {
      amount_minor: 5000,
      currency: "USD",
      organization_id: 42,
    },
  },
});
Direct REST request
curl https://our-impact.vercel.app/api/v1/events \
  --request POST \
  --header "Authorization: Bearer $OUR_IMPACT_SECRET_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "id": "donation_01JABC123",
    "type": "donation.completed",
    "external_user_id": "storefront:user_01JABC",
    "occurred_at": "2026-11-06T12:00:00Z",
    "properties": {
      "amount_minor": 5000,
      "currency": "USD",
      "organization_id": 42
    }
  }'

Shape events for durable rules

idRequired
A stable ID from the source system. Reuse it for retries; never generate a new ID merely because the first request timed out.
typeRequired
A namespaced, lowercase value such as donation.completed. Entitlement definitions match this value exactly.
externalUserIdRequired
The same immutable supporter ID used when creating browser identity tokens.
occurredAtOptional
When the activity really happened. Omit it only when API receipt time is the correct event time.
propertiesOptional
Verified facts available to rule filters and progress calculations. Store monetary amounts as integer minor units.

Idempotency is built into the event ID

Use the immediate evaluation result

201 Created
{
  "id": "d85b1407-351d-4694-9ac2-9c88b415c8c6",
  "replayed": false,
  "entitlements": [
    {
      "entitlement_key": "community_champion",
      "state": "active",
      "qualifying_count": 1,
      "progress_value": 5000,
      "progress_unit": "usd",
      "qualified_at": "2026-11-06T12:00:01Z",
      "valid_until": null,
      "updated_at": "2026-11-06T12:00:01Z"
    }
  ]
}

The response is useful for immediate server reactions. Monetary progress remains an integer in minor units: 5000 with usd means $50.00. Browser experiences should still fetch the current entitlement view using a fresh identity token.

Do not send untrusted browser claims