Users

Enroll a user before sending their purchases: Gave refuses a spend event or a claim for a user it doesn't know (422 UserNotEnrolled). A user is known by your own ID for them; Gave stores no names or emails.

Enroll a user

PUT enrolls the user, or replaces their attributes:

curl -X PUT https://api.sandbox.gave.sh/v1/users/alice \
  -H "x-api-key: $GAVE_API_KEY" \
  -H "content-type: application/json" \
  -d @enroll-user.json

enroll-user.json

{ "tier": "gold", "country": "FR", "segment": "premium" }

Field	What it is
`tier`	The user's tier: your programs give tiers multipliers and rates
`country`	Where the user lives, as an ISO 3166-1 alpha-2 code: programs can be limited to some countries
`segment`	A group of users you define: programs can be limited to some segments
`referredBy`	The user who referred them, enrolled before them. Set once, at enrollment

Every field is optional, and an attribute you leave out is cleared; referredBy is kept, as it's set once. The answer says what the request did: enrolled, updated or unchanged:

UserEnrollment

{
  "user": {
    "userId": "alice",
    "tier": "gold",
    "country": "FR",
    "segment": "premium",
    "enrolledAt": "2026-10-11T09:00:00.000Z",
    "updatedAt": "2026-10-11T09:00:00.000Z"
  },
  "outcome": "enrolled"
}

A purchase earns with the attributes the user had when it was made: a change applies from when you send it, never to purchases made before. The attributes you enroll a user with also apply to purchases made just before, such as one authorized yesterday and cleared today.

GET /v1/users/{userId} reads the user; it's a 404 for a user not enrolled, as their balance is.

List a user's rewards

GET /v1/users/{userId}/rewards lists a user's rewards, newest first, 50 at a time (limit, up to 100). Pass a page's next as cursor for the following one:

curl "https://api.sandbox.gave.sh/v1/users/alice/rewards?limit=1" -H "x-api-key: $GAVE_API_KEY"

RewardsPage

{
  "rewards": [
    {
      "id": "rw:acme:alice:clearing:txn_0001:everyday",
      "userId": "alice",
      "programId": "everyday",
      "transaction": { "kind": "clearing", "externalTransactionId": "txn_0001" },
      "state": "Pending",
      "amount": { "asset": "USDC", "amount": "500000" },
      "spend": { "currency": "USD", "amount": "5000" },
      "claimableAt": "2026-11-10T09:30:00.000Z"
    }
  ],
  "next": "41"
}

Each reward is as its webhooks describe it. Missed some webhooks? Rebuild a user's state from this list.