API Reference

Base URL: https://incenta.dev/api/v1

All endpoints require a Bearer token in the Authorization header.

Referrals

Create a referral code


POST /referrals

Generate a unique referral code for a campaign.


curl -X POST https://incenta.dev/api/v1/referrals \
  -H "Authorization: Bearer rk_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "camp_abc123",
    "referrerId": "user_456"
  }'

Request body:

Field	Type	Required	Description
`campaignId`	`string`	Yes	Campaign identifier
`referrerId`	`string`	Yes	ID of the user creating the referral
`refereeId`	`string`	No	ID of the referred user (if known)
`referrerUsername`	`string`	No	Display name for the referrer
`referrerEmail`	`string`	No	Email of the referrer

Response 201:


{
  "referralCode": "ABC123",
  "referralId": "ref_789",
  "status": "PENDING",
  "warning": null,
  "reasons": null,
  "riskScore": null
}

The response may include warning, reasons, and riskScore if the fraud detection system flagged the referral.

Lookup a referral


GET /referrals/{referralCode}

Get details about a specific referral code.


curl https://incenta.dev/api/v1/referrals/ABC123 \
  -H "Authorization: Bearer rk_xxxxx"

Response 200:


{
  "referral": {
    "id": "ref_789",
    "referralCode": "ABC123",
    "referrerId": "user_456",
    "refereeId": "user_789",
    "status": "PENDING",
    "level": 1,
    "rewardAmount": 5.00,
    "isFlagged": false,
    "createdAt": "2026-06-18T12:00:00.000Z",
    "Campaign": {
      "id": "camp_001",
      "name": "Summer Campaign",
      "status": "ACTIVE"
    }
  }
}

Clicks

Track a click


POST /clicks

Record when a user clicks a referral link.


curl -X POST https://incenta.dev/api/v1/clicks \
  -H "Authorization: Bearer rk_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "referralCode": "ABC123",
    "refereeId": "user_789"
  }'

Request body:

Field	Type	Required	Description
`referralCode`	`string`	Yes	The referral code that was clicked
`refereeId`	`string`	No	ID of the user who clicked

Response 200:


{
  "success": true,
  "clickId": "click_123",
  "referralCode": "ABC123",
  "clickedAt": "2026-06-18T12:00:00.000Z"
}

Conversions

Record a conversion


POST /conversions

Record that a referred user completed a desired action.


curl -X POST https://incenta.dev/api/v1/conversions \
  -H "Authorization: Bearer rk_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "referralCode": "ABC123",
    "refereeId": "user_789",
    "amount": 49.99,
    "metadata": { "orderId": "order_xyz" }
  }'

Request body:

Field	Type	Required	Description
`referralCode`	`string`	Yes	The referral code
`refereeId`	`string`	Yes	ID of the user who converted
`amount`	`number`	No	Monetary value of the conversion
`metadata`	`object`	No	Arbitrary key-value data

Response 201:


{
  "success": true,
  "referralId": "ref_789",
  "conversionId": "conv_456",
  "rewardAmount": 5.00,
  "rewardCreated": true,
  "status": "COMPLETED",
  "refereeId": "user_789",
  "referrerId": "user_456"
}

Fraud detection runs automatically. If the referral is flagged, the response includes warning and reasons fields.

List conversions


GET /conversions

Query parameters: ?campaignId&referralCode&status&page&limit

Param	Type	Description
`campaignId`	string	Filter by campaign
`referralCode`	string	Filter by original referral code
`status`	string	`PENDING`, `CLICKED`, `CONVERTED`, `FLAGGED`
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 25, max: 100)

Response 200:


{
  "conversions": [
    {
      "id": "conv_456",
      "referralCode": "XYZ789",
      "referrerId": "user_456",
      "refereeId": "user_789",
      "status": "CONVERTED",
      "rewardAmount": 5.00,
      "level": 1,
      "originalReferralCode": "ABC123",
      "convertedAt": "2026-06-20T12:00:00.000Z",
      "Campaign": {
        "id": "camp_001",
        "name": "Summer Campaign"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "totalItems": 1,
    "totalPages": 1
  }
}

Stats

Get referral stats


GET /stats

Aggregated statistics for a campaign.


curl "https://incenta.dev/api/v1/stats?campaignId=camp_abc123" \
  -H "Authorization: Bearer rk_xxxxx"

Query parameters:

Param	Type	Required	Description
`campaignId`	`string`	Yes	Campaign to get stats for

Response 200:


{
  "totalReferrals": 142,
  "totalClicks": 89,
  "totalConversions": 34,
  "conversionRate": 38.2,
  "totalRewardValue": 169.99
}

Rewards

List rewards


GET /rewards

Query parameters: ?userId&status&fulfillmentType&page&limit

Param	Values
`status`	`PENDING`, `APPROVED`, `PAID`, `CANCELLED`
`fulfillmentType`	`DISCOUNT_CODE`, `COUPON_CODE`, `MANUAL`, `AUTOMATED`, `GIFT_CARD`, `CUSTOM`

Get a reward


GET /rewards/{rewardId}

Claim a reward


POST /rewards/{rewardId}/claim

Claims a reward and returns a discount code or coupon.


curl -X POST https://incenta.dev/api/v1/rewards/rew_xyz/claim \
  -H "Authorization: Bearer rk_xxxxx"

Response 200:


{
  "success": true,
  "discountCode": "SAVE20",
  "expiresAt": "2026-07-06T12:00:00.000Z"
}

Validate a code


GET /rewards/validate

Query: ?code=DISCOUNT123

Returns whether the discount or coupon code is valid and its details.


curl "https://incenta.dev/api/v1/rewards/validate?code=DISCOUNT123" \
  -H "Authorization: Bearer rk_xxxxx"

Response 200:


{
  "valid": true,
  "code": "DISCOUNT123",
  "type": "PERCENTAGE",
  "discount": 20,
  "expiresAt": "2026-08-06T12:00:00.000Z"
}

Redeem a reward


POST /rewards/redeem

Marks a reward as fulfilled/redeemed.


curl -X POST https://incenta.dev/api/v1/rewards/redeem \
  -H "Authorization: Bearer rk_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "rewardId": "reward_xyz",
    "userId": "user_456"
  }'

Request body:

Field	Type	Required	Description
`rewardId`	`string`	Yes	ID of the reward to redeem
`userId`	`string`	Yes	ID of the user redeeming the reward

List user rewards


GET /users/{userId}/rewards

Incentive Engine

The incentive engine powers gamification: actions, XP, levels, badges, coins, tokens, and leaderboards.

Actions


GET    /incentives/actions
POST   /incentives/actions
PATCH  /incentives/actions/{key}

Define actions that users can perform to earn coins, XP, and tokens. Each action has a cooldown, max repeats, and configurable rewards.


curl -X POST https://incenta.dev/api/v1/incentives/actions \
  -H "Authorization: Bearer rk_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "complete_profile",
    "name": "Complete Profile",
    "type": "STANDARD",
    "coins": 50,
    "xp": 100,
    "maxRepeats": 1
  }'

POST body:

Field	Type	Required	Description
`key`	`string`	Yes	Unique action key
`name`	`string`	Yes	Display name
`type`	`string`	Yes	`STANDARD`, `REFERRAL_CODE_GENERATE`, `REFERRAL_CLICK`, or `REFERRAL_REFEREE_ACTION`
`coins`	`number`	No	Coins awarded
`xp`	`number`	No	XP awarded
`tokens`	`number`	No	Tokens awarded
`cooldown`	`number`	No	Cooldown in seconds
`maxRepeats`	`number`	No	Max times a user can earn this reward

Events


GET    /incentives/events
POST   /incentives/events
POST   /incentives/events/bulk

Record a user completing an action.


curl -X POST https://incenta.dev/api/v1/incentives/events \
  -H "Authorization: Bearer rk_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_456",
    "actionKey": "complete_profile",
    "idempotencyKey": "idem_abc123",
    "metadata": { "source": "web" }
  }'

POST /incentives/events body:

Field	Type	Required	Description
`userId`	`string`	Yes	User identifier
`actionKey`	`string`	Yes	Key of the action completed
`idempotencyKey`	`string`	No	Prevents duplicate processing
`metadata`	`object`	No	Additional data


curl -X POST https://incenta.dev/api/v1/incentives/events/bulk \
  -H "Authorization: Bearer rk_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      { "userId": "user_456", "actionKey": "daily_login", "idempotencyKey": "user_login_1" },
      { "userId": "user_456", "actionKey": "share_product", "idempotencyKey": "user_share_1" }
    ]
  }'

POST /incentives/events/bulk body:

Field	Type	Required	Description
`events`	`array`	Yes	Array of event objects

Each event object supports the same fields as a single event:

Field	Type	Required	Description
`userId`	`string`	Yes	User identifier
`actionKey`	`string`	Yes	Key of the action completed
`idempotencyKey`	`string`	No	Prevents duplicate processing
`metadata`	`object`	No	Additional data

Balances


GET  /incentives/balances
GET  /incentives/balances/{userId}

Get user coin, token, and XP balances.

Levels


GET    /incentives/levels
POST   /incentives/levels
PATCH  /incentives/levels/{level}
DELETE /incentives/levels/{level}

Define XP thresholds for levels. Each level can grant coins, a badge, and perks.

Badges


GET    /incentives/badges
POST   /incentives/badges
PATCH  /incentives/badges/{key}
GET    /incentives/badges/user/{userId}

Define and award badges to users.

Catalog


GET    /incentives/catalog
POST   /incentives/catalog
GET    /incentives/catalog/{itemId}
PATCH  /incentives/catalog/{itemId}
DELETE /incentives/catalog/{itemId}

Create redeemable items that users can buy with coins or tokens.

Response 200:


{
  "items": [
    {
      "id": "item_xyz",
      "name": "10% Discount Code",
      "description": "Get 10% off your next order",
      "coinCost": 500,
      "tokenCost": 0,
      "inventory": -1,
      "published": true
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "totalItems": 1,
    "totalPages": 1
  }
}


curl -X POST https://incenta.dev/api/v1/incentives/catalog \
  -H "Authorization: Bearer rk_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "10% Discount Code",
    "description": "Get 10% off your next order",
    "coinCost": 500,
    "inventory": -1,
    "published": true
  }'

POST body:

Field	Type	Required	Description
`name`	`string`	Yes	Display name of the item
`description`	`string`	No	Description of the item
`coinCost`	`number`	Yes	Cost in coins
`tokenCost`	`number`	No	Cost in tokens (default: 0)
`inventory`	`number`	No	Stock count (`-1` for unlimited)
`published`	`boolean`	No	Whether the item is visible to users

Redemptions


POST  /incentives/redeem
GET   /incentives/redemptions
PATCH /incentives/redemptions/{id}

Users redeem catalog items. Statuses: PENDING, FULFILLED, CANCELLED.

Response 200:


{
  "redemptions": [
    {
      "id": "redemption_xyz",
      "userId": "user_456",
      "itemId": "item_xyz",
      "status": "PENDING",
      "redeemedAt": "2026-07-06T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "totalItems": 1,
    "totalPages": 1
  }
}


curl -X POST https://incenta.dev/api/v1/incentives/redeem \
  -H "Authorization: Bearer rk_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_456",
    "itemId": "item_xyz"
  }'

POST /incentives/redeem body:

Field	Type	Required	Description
`userId`	`string`	Yes	ID of the user redeeming
`itemId`	`string`	Yes	ID of the catalog item to redeem

PATCH /incentives/redemptions/{id} body:

Field	Type	Required	Description
`status`	`string`	Yes	New status: `FULFILLED` or `CANCELLED`

Leaderboard


GET  /incentives/leaderboard
POST /incentives/leaderboard
GET  /incentives/leaderboard/{userId}
POST /incentives/leaderboard/refresh

Real-time leaderboard ranked by XP, with periodic snapshots.


curl https://incenta.dev/api/v1/incentives/leaderboard?limit=10 \
  -H "Authorization: Bearer rk_xxxxx"

POST /incentives/leaderboard body:

Field	Type	Required	Description
`userId`	`string`	Yes	User identifier
`xp`	`number`	Yes	XP score
`coins`	`number`	No	Coin balance

Milestones


GET /incentives/milestones

List milestones achieved by users (e.g., “1000 XP reached”).

Marketplace

The rewards marketplace lets businesses list rewards that users from other apps can redeem with coins or tokens.

List public listings


GET /incentives/marketplace/public/listings
GET /incentives/marketplace/public/listings/{id}

Browse available marketplace listings and get details on a specific listing.

Verify a redemption


GET /incentives/marketplace/verify/{id}

Verify the validity of a marketplace redemption code.

User Endpoints

Get user stats


GET /users/{userId}/stats


curl "https://incenta.dev/api/v1/users/user_456/stats?campaignId=camp_abc123" \
  -H "Authorization: Bearer rk_xxxxx"

Get aggregated referral statistics for a specific user.

List user rewards


GET /users/{userId}/rewards


curl "https://incenta.dev/api/v1/users/user_456/rewards?limit=10" \
  -H "Authorization: Bearer rk_xxxxx"

List all rewards earned by a specific user.