Invitebase | Rewards

A Reward records what is owed once a referral validates, and tracks its fulfillment. Rewards are created automatically on validation from the campaign's reward configuration — the API never creates them. A reward is created pending and becomes approved when the referral's fraud decision lands — which happens on the pass that validates the referral — then waits out any hold window. A referral the fraud rules reject rejects its rewards with it. Money-rail rewards are fulfilled by the payout provider; app grants (in_app, free_access) are granted by your backend, which confirms the grant so the record reads fulfilled — see In-app reward webhooks.

The Reward object

Field	Type	Description
`id`	string	Unique identifier (a UUID).
`object`	string	Always `reward`.
`status`	string	Lifecycle state — see the status table.
`referral_id`	string	The Referral that earned this reward.
`campaign_id`	string	The Campaign it came from.
`recipient`	string	`referrer` or `referred_user`. Double-sided campaigns create one reward per side.
`config`	object	The RewardConfiguration snapshot this reward was created from — the `method`, and the amount and currency for money rails.
`mode`	string	`test` or `live`.
`livemode`	boolean	Whether the reward exists in live mode.
`created_at`	string (date-time)	Creation time.

Reward statuses

Status	Meaning
`pending`	Created on validation, before the fraud decision is applied. For app grants this is the acting state: `reward.pending` fires and your backend confirms the grant.
`held_for_review`	Held back from fulfillment, and blocked from being fulfilled until it is approved. Fires `reward.held_for_review`. Automatic fraud decisions never produce it — they approve or reject outright.
`approved`	The referral's fraud decision approved it; queued for fulfillment once any hold window elapses.
`fulfilled`	Delivered — app grants when your backend confirms the grant; payouts when the provider completes.
`failed`	Payout fulfillment failed (money rewards only, e.g. payout error). App grants cannot fail.
`rejected`	Rejected with its referral by the fraud rules, or clawed back inside the hold window. Never paid, never billed.

List rewards

GET/v1/rewards

Returns a paginated list of rewards, filterable by campaign, referral, referrer, and status.

Parameter	In	Type	Required	Description
`limit`	query	integer	No	1–100, default 25.
`starting_after`	query	string	No	Cursor (reward id) for the next page.
`campaign_id`	query	string	No	Only rewards from this campaign.
`referral_id`	query	string	No	Only rewards earned by this referral.
`referrer_id`	query	string	No	Only rewards from referrals made by this referrer.
`status`	query	string	No	Only rewards in this status, e.g. `pending`.

curl "https://api.invitebase.com/v1/rewards?status=pending" \
  -H "Authorization: Bearer $INVITEBASE_SECRET_KEY"

Response — 200 OK:

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "4b7d9e2f-8c15-4a63-b0d9-5e2f8a1c6d47",
      "object": "reward",
      "status": "pending",
      "referral_id": "2c9d4e7f-1a63-48b5-8e02-6f3a9b1d5c74",
      "campaign_id": "7e1f8a3b-4c26-49d0-b591-0d8e2f6a3c15",
      "recipient": "referrer",
      "config": {
        "method": "gift_card",
        "recipient": "referrer",
        "amount": 1000,
        "currency": "usd"
      },
      "mode": "test",
      "livemode": false,
      "created_at": "2026-07-08T18:20:06.000Z"
    }
  ]
}

Retrieve a reward

GET/v1/rewards/{rewardId}

Returns the reward.

Parameter	In	Type	Required	Description
`rewardId`	path	string	Yes	The reward id.

curl https://api.invitebase.com/v1/rewards/4b7d9e2f-8c15-4a63-b0d9-5e2f8a1c6d47 \
  -H "Authorization: Bearer $INVITEBASE_SECRET_KEY"

Response — 200 OK: the Reward object. Returns 404 if the reward does not exist.

Fulfill a reward

POST/v1/rewards/{rewardId}/fulfill

The app-grant acknowledgement: your backend grants the entitlement in its own system — typically from a reward.pending webhook — and confirms it here, moving the reward to fulfilled. The ack is idempotent: fulfilling an already-fulfilled reward returns it unchanged, so it is safe inside a retried webhook handler.

Parameter	In	Type	Required	Description
`rewardId`	path	string	Yes	The reward id.

curl -X POST https://api.invitebase.com/v1/rewards/9d2e6f4a-3b81-47c5-a0e6-8f1d5c7b2e94/fulfill \
  -H "Authorization: Bearer $INVITEBASE_SECRET_KEY"

Response — 200 OK:

{
  "id": "9d2e6f4a-3b81-47c5-a0e6-8f1d5c7b2e94",
  "object": "reward",
  "status": "fulfilled",
  "referral_id": "2c9d4e7f-1a63-48b5-8e02-6f3a9b1d5c74",
  "campaign_id": "7e1f8a3b-4c26-49d0-b591-0d8e2f6a3c15",
  "recipient": "referred_user",
  "config": {
    "method": "free_access",
    "recipient": "referred_user",
    "free_access_duration": { "count": 1, "unit": "month" }
  },
  "mode": "test",
  "livemode": false,
  "created_at": "2026-07-08T18:20:06.000Z"
}

Only app-grant rewards (in_app, free_access) are acknowledged here. Returns 409 if the reward pays out through a money rail (those are fulfilled by the payout provider), is held_for_review (it must be approved first), or was rejected. Returns 404 if the reward does not exist. See Errors.

What's next

In-app reward webhooks

Grant app rewards from your backend and confirm them.

Balance

Your prefunded reward balance and top-ups.

Webhook endpoints

Integrations

Connected event sources — RevenueCat, Adapty, Stripe, Segment.