Loyalty

GET/api/v1/loyalty/campaigns

List campaigns

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Query Parameters

q?string

Full-text search query applied to campaign description

page?integer

1-indexed page number

Formatint64

Range0 <= value

page_size?integer

Page size

Formatint64

Range0 <= value

sort_by?string

Sort field (created_at, updated_at, start_date, end_date)

sort_order?string

Sort order (asc or desc)

Value in

"asc"
"desc"

filter?array<string>

Additional filter expressions in the form field:operator:value

active_only?boolean

Only return active campaigns

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/loyalty/campaigns"

{  "campaigns": [    {      "active": true,      "campaign_id": "string",      "campaign_type": "referral",      "created_at": "2019-08-24T14:15:22Z",      "description": "string",      "end_date": "2019-08-24T14:15:22Z",      "rewards": {        "referee_reward": null,        "referrer_reward": null      },      "rules": {        "allow_self_referral": true,        "attribution_window_days": 0,        "block_same_ip": true,        "custom_rules": [          "string"        ],        "max_referrals_per_user": 0,        "min_purchase_amount": 0,        "require_email_verification": true      },      "start_date": "2019-08-24T14:15:22Z",      "triggers": [        {          "action": "complete_referral",          "event_name": "string",          "filters": null        }      ],      "updated_at": "2019-08-24T14:15:22Z"    }  ],  "pagination": {    "has_more": true,    "page": 0,    "page_size": 0,    "total": 0  }}

POST/api/v1/loyalty/campaigns

Create a new campaign

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Request to create a new campaign

active?boolean

campaign_id*string

campaign_type*CampaignType

Campaign type enumeration

Value in

"referral"
"points"
"tiered"

description*string

end_date?|

Formatdate-time

rewards*

Campaign rewards structure

rules*

Campaign rules configuration

start_date?|

Formatdate-time

triggers*array<>

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/loyalty/campaigns" \  -H "Content-Type: application/json" \  -d '{    "campaign_id": "string",    "campaign_type": "referral",    "description": "string",    "rewards": {},    "rules": {      "attribution_window_days": 0    },    "triggers": [      {        "action": "complete_referral",        "event_name": "string"      }    ]  }'

{  "campaign": {    "active": true,    "campaign_id": "string",    "campaign_type": "referral",    "created_at": "2019-08-24T14:15:22Z",    "description": "string",    "end_date": "2019-08-24T14:15:22Z",    "rewards": {      "referee_reward": null,      "referrer_reward": null    },    "rules": {      "allow_self_referral": true,      "attribution_window_days": 0,      "block_same_ip": true,      "custom_rules": [        "string"      ],      "max_referrals_per_user": 0,      "min_purchase_amount": 0,      "require_email_verification": true    },    "start_date": "2019-08-24T14:15:22Z",    "triggers": [      {        "action": "complete_referral",        "event_name": "string",        "filters": null      }    ],    "updated_at": "2019-08-24T14:15:22Z"  }}

GET/api/v1/loyalty/campaigns/{campaign_id}

Get a campaign

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

campaign_id*string

Campaign ID

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/loyalty/campaigns/string"

{  "campaign": {    "active": true,    "campaign_id": "string",    "campaign_type": "referral",    "created_at": "2019-08-24T14:15:22Z",    "description": "string",    "end_date": "2019-08-24T14:15:22Z",    "rewards": {      "referee_reward": null,      "referrer_reward": null    },    "rules": {      "allow_self_referral": true,      "attribution_window_days": 0,      "block_same_ip": true,      "custom_rules": [        "string"      ],      "max_referrals_per_user": 0,      "min_purchase_amount": 0,      "require_email_verification": true    },    "start_date": "2019-08-24T14:15:22Z",    "triggers": [      {        "action": "complete_referral",        "event_name": "string",        "filters": null      }    ],    "updated_at": "2019-08-24T14:15:22Z"  },  "stats": null}

PATCH/api/v1/loyalty/campaigns/{campaign_id}

Update a campaign's description, activation, rules, triggers, or rewards

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

campaign_id*string

Campaign ID

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Request to update campaign configuration

active?boolean|null

description?string|null

rewards?null|

rules?null|

triggers?array<>|null

Response Body

`application/json`

curl -X PATCH "https://example.com/api/v1/loyalty/campaigns/string" \  -H "Content-Type: application/json" \  -d '{}'

{  "campaign": {    "active": true,    "campaign_id": "string",    "campaign_type": "referral",    "created_at": "2019-08-24T14:15:22Z",    "description": "string",    "end_date": "2019-08-24T14:15:22Z",    "rewards": {      "referee_reward": null,      "referrer_reward": null    },    "rules": {      "allow_self_referral": true,      "attribution_window_days": 0,      "block_same_ip": true,      "custom_rules": [        "string"      ],      "max_referrals_per_user": 0,      "min_purchase_amount": 0,      "require_email_verification": true    },    "start_date": "2019-08-24T14:15:22Z",    "triggers": [      {        "action": "complete_referral",        "event_name": "string",        "filters": null      }    ],    "updated_at": "2019-08-24T14:15:22Z"  }}

DELETE/api/v1/loyalty/campaigns/{campaign_id}

Delete a campaign

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

campaign_id*string

Campaign ID

Response Body

curl -X DELETE "https://example.com/api/v1/loyalty/campaigns/string"

Empty

GET/api/v1/loyalty/campaigns/{campaign_id}/analytics

Get campaign analytics

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

campaign_id*string

Campaign ID

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/loyalty/campaigns/string/analytics"

{  "campaign_id": "string",  "end_date": "2019-08-24T14:15:22Z",  "start_date": "2019-08-24T14:15:22Z",  "stats": {    "conversion_rate": 0.1,    "total_conversions": 0,    "total_participants": 0,    "total_referrals": 0,    "total_rewards_distributed": 0.1  }}

POST/api/v1/loyalty/codes

Create a referral code

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Request to create a referral code

campaign_id*string

custom_code?string|null

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/loyalty/codes" \  -H "Content-Type: application/json" \  -d '{    "campaign_id": "string"  }'

{  "campaign_id": "string",  "referral_code": "string",  "referral_link": "string",  "user_id": "string"}

POST/api/v1/loyalty/events

Ingest a loyalty event and apply matching campaign rules

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Request to track a loyalty event

context?unknown

event_name*string

timestamp?|

Formatdate-time

user_id*string

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/loyalty/events" \  -H "Content-Type: application/json" \  -d '{    "event_name": "string",    "user_id": "string"  }'

{  "event_id": "string",  "matched_campaigns": [    "string"  ],  "payouts": [    {      "beneficiary": "referrer",      "campaign_id": "string",      "created_at": "2019-08-24T14:15:22Z",      "paid_at": "2019-08-24T14:15:22Z",      "payout_id": "string",      "referral_id": "string",      "reward_type": "credit",      "status": "pending",      "transaction_id": "string",      "user_id": "string",      "value": 0.1    }  ],  "points_granted": 0,  "processed": true,  "referral": null}

POST/api/v1/loyalty/referrals

Create a referral tracking record from a referral code

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Request to create a referral tracking record (signup attribution)

device_fingerprint?string|null

ip_address?string|null

referee_id*string

referral_code*string

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/loyalty/referrals" \  -H "Content-Type: application/json" \  -d '{    "referee_id": "string",    "referral_code": "string"  }'

{  "referral": {    "campaign_id": "string",    "context": null,    "converted_at": "2019-08-24T14:15:22Z",    "created_at": "2019-08-24T14:15:22Z",    "fsm_name": "string",    "referee_id": "string",    "referral_code": "string",    "referral_id": "string",    "referrer_id": "string",    "status": "pending"  }}

POST/api/v1/loyalty/referrals/validate

Validate a referral without persisting

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Request to validate a referral

device_fingerprint?string|null

ip_address?string|null

referee_id*string

referral_code*string

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/loyalty/referrals/validate" \  -H "Content-Type: application/json" \  -d '{    "referee_id": "string",    "referral_code": "string"  }'

{  "reasons": [    "string"  ],  "valid": true}

GET/api/v1/loyalty/rewards

List reward catalog items

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Query Parameters

page?integer

1-indexed page number

Formatint64

Range0 <= value

page_size?integer

Page size

Formatint64

Range0 <= value

active_only?boolean

Only return active rewards

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/loyalty/rewards"

{  "pagination": {    "has_more": true,    "page": 0,    "page_size": 0,    "total": 0  },  "rewards": [    {      "active": true,      "created_at": "2019-08-24T14:15:22Z",      "description": "string",      "fulfillment_data": null,      "name": "string",      "points_cost": 0,      "reward_id": "string",      "stock": 0,      "updated_at": "2019-08-24T14:15:22Z"    }  ]}

POST/api/v1/loyalty/rewards

Create a reward catalog item

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Request to create a reward catalog item

active?boolean

description*string

fulfillment_data?unknown

name*string

points_cost*integer

Formatint64

reward_id*string

stock?|

Formatint64

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/loyalty/rewards" \  -H "Content-Type: application/json" \  -d '{    "description": "string",    "name": "string",    "points_cost": 0,    "reward_id": "string"  }'

{  "reward": {    "active": true,    "created_at": "2019-08-24T14:15:22Z",    "description": "string",    "fulfillment_data": null,    "name": "string",    "points_cost": 0,    "reward_id": "string",    "stock": 0,    "updated_at": "2019-08-24T14:15:22Z"  }}

GET/api/v1/loyalty/rewards/{reward_id}

Get a reward catalog item

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

reward_id*string

Reward ID

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/loyalty/rewards/string"

{  "reward": {    "active": true,    "created_at": "2019-08-24T14:15:22Z",    "description": "string",    "fulfillment_data": null,    "name": "string",    "points_cost": 0,    "reward_id": "string",    "stock": 0,    "updated_at": "2019-08-24T14:15:22Z"  }}

PATCH/api/v1/loyalty/rewards/{reward_id}

Update a reward catalog item

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

reward_id*string

Reward ID

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Request to update a reward catalog item

active?boolean|null

description?string|null

fulfillment_data?unknown

name?string|null

points_cost?|

Formatint64

stock?|

Formatint64

Response Body

`application/json`

curl -X PATCH "https://example.com/api/v1/loyalty/rewards/string" \  -H "Content-Type: application/json" \  -d '{}'

{  "reward": {    "active": true,    "created_at": "2019-08-24T14:15:22Z",    "description": "string",    "fulfillment_data": null,    "name": "string",    "points_cost": 0,    "reward_id": "string",    "stock": 0,    "updated_at": "2019-08-24T14:15:22Z"  }}

GET/api/v1/loyalty/users/{user_id}/codes

Get user's referral codes

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

user_id*string

User ID

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/loyalty/users/string/codes"

{  "codes": [    {      "campaign_id": "string",      "created_at": "2019-08-24T14:15:22Z",      "id": "string",      "referral_code": "string",      "referral_link": "string",      "referrer": "string"    }  ]}

GET/api/v1/loyalty/users/{user_id}/dashboard

Get a participant dashboard

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

user_id*string

User ID

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/loyalty/users/string/dashboard"

{  "dashboard": {    "campaigns": [      {        "campaign_id": "string",        "referral_code": "string",        "stats": {          "conversion_rate": 0.1,          "paid_rewards": 0.1,          "pending_rewards": 0.1,          "total_clicks": 0,          "total_conversions": 0,          "total_signups": 0        }      }    ],    "recent_referrals": [      {        "campaign_id": "string",        "context": null,        "converted_at": "2019-08-24T14:15:22Z",        "created_at": "2019-08-24T14:15:22Z",        "fsm_name": "string",        "referee_id": "string",        "referral_code": "string",        "referral_id": "string",        "referrer_id": "string",        "status": "pending"      }    ],    "total_earnings": 0.1,    "total_points": 0,    "user_id": "string"  }}

GET/api/v1/loyalty/users/{user_id}/points/balance

Get points balance

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

user_id*string

User ID

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/loyalty/users/string/points/balance"

{  "balance": {    "balance": 0,    "lifetime_earned": 0,    "lifetime_redeemed": 0,    "updated_at": "2019-08-24T14:15:22Z",    "user_id": "string"  }}

POST/api/v1/loyalty/users/{user_id}/points/grant

Grant points to a user

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

user_id*string

User ID

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Request to manually grant points

campaign_id?string|null

points*integer

Formatint64

reason*string

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/loyalty/users/string/points/grant" \  -H "Content-Type: application/json" \  -d '{    "points": 0,    "reason": "string"  }'

{  "new_balance": 0,  "points_credited": 0,  "reason": "string",  "transaction_id": "string",  "user_id": "string"}

GET/api/v1/loyalty/users/{user_id}/points/history

Get points transaction history for a user

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

user_id*string

User ID

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/loyalty/users/string/points/history"

{  "total": 0,  "transactions": [    {      "amount": 0,      "balance_after": 0,      "campaign_id": "string",      "created_at": "2019-08-24T14:15:22Z",      "reason": "string",      "transaction_id": "string",      "transaction_type": "string",      "user_id": "string"    }  ]}

POST/api/v1/loyalty/users/{user_id}/points/redeem

Redeem points for a catalog reward

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

user_id*string

User ID

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Request to redeem points

metadata?unknown

points*integer

Formatint64

reward_id*string

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/loyalty/users/string/points/redeem" \  -H "Content-Type: application/json" \  -d '{    "points": 0,    "reward_id": "string"  }'

{  "fulfillment_data": null,  "new_balance": 0,  "points_spent": 0,  "redemption_id": "string",  "reward_id": "string",  "user_id": "string"}

GET/api/v1/loyalty/users/{user_id}/redemptions

List a user's redemptions

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

user_id*string

User ID

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/loyalty/users/string/redemptions"

{  "redemptions": [    {      "balance_after": 0,      "created_at": "2019-08-24T14:15:22Z",      "fulfillment_data": null,      "points_spent": 0,      "redemption_id": "string",      "reward_id": "string",      "transaction_id": "string",      "user_id": "string"    }  ]}

Loyalty

200application/json

503

201application/json

400

409

503

200application/json

404

503

200application/json

404

503

204

404

503

200application/json

404

503

201application/json

400

503

200application/json

400

503

201application/json

400

403

404

409

429

503

200application/json

503

200application/json

503

201application/json

400

409

503

200application/json

404

503

200application/json

404

503

200application/json

503

200application/json

403

503

200application/json

503

200application/json

400

503

200application/json

503

200application/json

400

403

404

503

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`