Loyalty Programs

Server

Customer loyalty programs, points, tiers, and rewards

Import members from CSV data

POST

https://common-api.karma.life

/api/v1/loyalty/{programId}/import

Import multiple members into a loyalty program from parsed CSV data. Supports name, email, phone, initial points, and enrolled date. Creates users if they do not exist.

Permissions: 🟢 loyalty.create

Import members from CSV data › path Parameters

programId

string · pattern: ^[0-9]+$ · required

Loyalty program ID

Import members from CSV data › Request Body

object[] · minItems: 1 · maxItems: 5000 · required

Array of member objects to import

Import members from CSV data › Responses

Default Response

status

string · enum

Enum values:

success

object

POST/api/v1/loyalty/{programId}/import

curl --request POST \
  --url https://common-api.karma.life/api/v1/loyalty/:programId/import \
  --header 'Content-Type: application/json' \
  --data '
{
  "members": [
    {
      "name": "name",
      "email": "email",
      "phone": "phone",
      "points": 0,
      "enrolledAt": "enrolledAt",
      "tier": "tier"
    }
  ]
}
'

Example Request Body

{
  "members": [
    {
      "name": "name",
      "email": "email",
      "phone": "phone",
      "points": 0,
      "enrolledAt": "enrolledAt",
      "tier": "tier"
    }
  ]
}

Example Responses

No example specified for this content type

application/json

List loyalty members

GET

https://common-api.karma.life

/api/v1/loyalty/{programId}/members

Get all members of a loyalty program with pagination and search

Permissions: 🔵 loyalty.read

List loyalty members › path Parameters

programId

string · pattern: ^[0-9]+$ · required

Loyalty program ID

List loyalty members › query Parameters

page

number · min: 1

Page number

Default: 1

limit

number · min: 1 · max: 1000

Items per page

Default: 50

sort

string

Sort field (created_at, current_balance, lifetime_earned, lifetime_redeemed, user_name, user_email, tier_name)

order

string · enum

Sort order

Enum values:

asc

desc

Default: asc

search

string

Search by name, email, or phone

tierId

string

Filter by tier ID, or "none" for members without a tier

startDate

string · date-time

Filter members enrolled on or after this date (ISO 8601)

endDate

string · date-time

Filter members enrolled on or before this date (ISO 8601)

minBalance

number

Minimum current balance

maxBalance

number

Maximum current balance

minLifetimeEarned

number

Minimum lifetime earned points

maxLifetimeEarned

number

Maximum lifetime earned points

minLifetimeRedeemed

number

Minimum lifetime redeemed points

maxLifetimeRedeemed

number

Maximum lifetime redeemed points

List loyalty members › Responses

Default Response

status

string · enum

Enum values:

success

object

GET/api/v1/loyalty/{programId}/members

curl --request GET \
  --url https://common-api.karma.life/api/v1/loyalty/:programId/members

Example Responses

No example specified for this content type

application/json

Get member details

GET

https://common-api.karma.life

/api/v1/loyalty/{programId}/members/{userId}

Get detailed member information including account, user info, tier, and program details

Permissions: 🔵 loyalty.read

Get member details › path Parameters

programId

string · pattern: ^[0-9]+$ · required

Loyalty program ID

userId

string · pattern: ^[0-9]+$ · required

User ID

Get member details › Responses

Default Response

status

string · enum

Enum values:

success

object

GET/api/v1/loyalty/{programId}/members/{userId}

curl --request GET \
  --url https://common-api.karma.life/api/v1/loyalty/:programId/members/:userId

Example Responses

No example specified for this content type

application/json

Adjust member points

POST

https://common-api.karma.life

/api/v1/loyalty/{programId}/members/{userId}/adjust-points

Manually adjust a member's points balance (add or remove points)

Permissions: 🟠 loyalty.update

Adjust member points › path Parameters

programId

string · pattern: ^[0-9]+$ · required

Loyalty program ID

userId

string · pattern: ^[0-9]+$ · required

User ID

Adjust member points › Request Body

points

number · required

Points to add (positive) or remove (negative)

reason

string · required

Human-readable reason for the adjustment

Adjust member points › Responses

Default Response

status

string · enum

Enum values:

success

object

POST/api/v1/loyalty/{programId}/members/{userId}/adjust-points

curl --request POST \
  --url https://common-api.karma.life/api/v1/loyalty/:programId/members/:userId/adjust-points \
  --header 'Content-Type: application/json' \
  --data '
{
  "points": 0,
  "reason": "reason"
}
'

Example Request Body

{
  "points": 0,
  "reason": "reason"
}

Example Responses

No example specified for this content type

application/json

Get member redemptions

GET

https://common-api.karma.life

/api/v1/loyalty/{programId}/members/{userId}/redemptions

Get a member's reward redemption history

Permissions: 🔵 loyalty.read

Get member redemptions › path Parameters

programId

string · pattern: ^[0-9]+$ · required

Loyalty program ID

userId

string · pattern: ^[0-9]+$ · required

User ID

Get member redemptions › Responses

Default Response

status

string · enum

Enum values:

success

object

GET/api/v1/loyalty/{programId}/members/{userId}/redemptions

curl --request GET \
  --url https://common-api.karma.life/api/v1/loyalty/:programId/members/:userId/redemptions

Example Responses

No example specified for this content type

application/json

Assign tier to member

PUT

https://common-api.karma.life

/api/v1/loyalty/{programId}/members/{userId}/tier

Manually assign a tier override to a loyalty program member. Assignment type is inferred from auth context (manual for staff JWT, campaign for API key). Optional expiration date.

Permissions: ⚪ loyalty.tier.assign

Assign tier to member › path Parameters

programId

string · pattern: ^[0-9]+$ · required

Loyalty program ID

userId

string · pattern: ^[0-9]+$ · required

User ID

Assign tier to member › Request Body

tierId

number · required

Tier ID to assign

expiresAt

string | null · date-time

Optional expiration date (ISO 8601)

Assign tier to member › Responses

Default Response

status

string · enum

Enum values:

success

object

PUT/api/v1/loyalty/{programId}/members/{userId}/tier

curl --request PUT \
  --url https://common-api.karma.life/api/v1/loyalty/:programId/members/:userId/tier \
  --header 'Content-Type: application/json' \
  --data '
{
  "tierId": 0,
  "expiresAt": "2024-08-25T15:00:00Z"
}
'

Example Request Body

{
  "tierId": 0,
  "expiresAt": "2024-08-25T15:00:00Z"
}

Example Responses

No example specified for this content type

application/json

Remove tier override from member

DELETE

https://common-api.karma.life

/api/v1/loyalty/{programId}/members/{userId}/tier

Remove a manual/campaign tier override from a loyalty program member, reverting to automatic point-calculated tier.

Permissions: ⚪ loyalty.tier.assign

Remove tier override from member › path Parameters

programId

string · pattern: ^[0-9]+$ · required

Loyalty program ID

userId

string · pattern: ^[0-9]+$ · required

User ID

Remove tier override from member › Responses

Default Response

status

string · enum

Enum values:

success

object

DELETE/api/v1/loyalty/{programId}/members/{userId}/tier

curl --request DELETE \
  --url https://common-api.karma.life/api/v1/loyalty/:programId/members/:userId/tier

Example Responses

No example specified for this content type

application/json

Generate wallet pass

GET

https://common-api.karma.life

/api/v1/loyalty/{programId}/members/{userId}/wallet-pass

Generate Apple or Google Wallet pass for loyalty member

Generate wallet pass › path Parameters

programId

string · required

Loyalty program ID

userId

string · required

User ID

Generate wallet pass › query Parameters

platform

string · enum

apple (default) returns a .pkpass binary; google returns JSON { saveUrl }

Enum values:

apple

google

Generate wallet pass › Responses

Apple Wallet Pass file (.pkpass)

string

GET/api/v1/loyalty/{programId}/members/{userId}/wallet-pass

curl --request GET \
  --url https://common-api.karma.life/api/v1/loyalty/:programId/members/:userId/wallet-pass

Example Responses

No example specified for this content type

application/vnd.apple.pkpass

Redeem a reward

POST

https://common-api.karma.life

/api/v1/loyalty/{programId}/redeem/{rewardId}

Redeem a reward for a user, deducting points and generating a voucher code

Permissions: 🟢 loyalty.create

Redeem a reward › path Parameters

programId

string · pattern: ^[0-9]+$ · required

Loyalty program ID

rewardId

string · pattern: ^[0-9]+$ · required

Reward catalog item ID

Redeem a reward › Request Body

userId

number · required

User ID redeeming the reward

Redeem a reward › Responses

Default Response

status

string · enum

Enum values:

success

object

POST/api/v1/loyalty/{programId}/redeem/{rewardId}

curl --request POST \
  --url https://common-api.karma.life/api/v1/loyalty/:programId/redeem/:rewardId \
  --header 'Content-Type: application/json' \
  --data '{
  "userId": 0
}'

Example Request Body

{
  "userId": 0
}

Example Responses

No example specified for this content type

application/json

Create earning rule

POST

https://common-api.karma.life

/api/v1/loyalty/earning-rules

Create a new earning rule for a loyalty program

Permissions: 🟢 loyalty.create

Create earning rule › Request Body

loyaltyProgramId

number · required

name

string · minLength: 1 · required

ruleType

string · enum · required

Enum values:

SPEND_BASED

ITEM_BASED

VISIT_BASED

ACTION_BASED

description

string

isActive

boolean

Default: true

minTierId

number

pointsPerCurrencyUnit

number

minPurchaseAmount

number

itemId

number

pointsMode

string · enum

Enum values:

FIXED

MULTIPLIER

pointsPerItem

number

pointsMultiplier

number

pointsPerVisit

number

minPurchaseForVisit

number

actionType

string

pointsPerAction

number

maxActionsPerPeriod

number

actionPeriod

string

validFrom

string | null · date

validUntil

string | null · date

priority

number

Default: 0

Create earning rule › Responses

Default Response

status

string · enum

Enum values:

success

object

POST/api/v1/loyalty/earning-rules

curl --request POST \
  --url https://common-api.karma.life/api/v1/loyalty/earning-rules \
  --header 'Content-Type: application/json' \
  --data '
{
  "loyaltyProgramId": 0,
  "name": "name",
  "description": "description",
  "ruleType": "SPEND_BASED",
  "isActive": true,
  "minTierId": 0,
  "pointsPerCurrencyUnit": 0,
  "minPurchaseAmount": 0,
  "itemId": 0,
  "pointsMode": "FIXED",
  "pointsPerItem": 0,
  "pointsMultiplier": 0,
  "pointsPerVisit": 0,
  "minPurchaseForVisit": 0,
  "actionType": "actionType",
  "pointsPerAction": 0,
  "maxActionsPerPeriod": 0,
  "actionPeriod": "actionPeriod",
  "validFrom": "2024-08-25",
  "validUntil": "2024-08-25",
  "priority": 0
}
'

Example Request Body

{
  "loyaltyProgramId": 0,
  "name": "name",
  "description": "description",
  "ruleType": "SPEND_BASED",
  "isActive": true,
  "minTierId": 0,
  "pointsPerCurrencyUnit": 0,
  "minPurchaseAmount": 0,
  "itemId": 0,
  "pointsMode": "FIXED",
  "pointsPerItem": 0,
  "pointsMultiplier": 0,
  "pointsPerVisit": 0,
  "minPurchaseForVisit": 0,
  "actionType": "actionType",
  "pointsPerAction": 0,
  "maxActionsPerPeriod": 0,
  "actionPeriod": "actionPeriod",
  "validFrom": "2024-08-25",
  "validUntil": "2024-08-25",
  "priority": 0
}

Example Responses

No example specified for this content type

application/json

Update earning rule

PUT

https://common-api.karma.life

/api/v1/loyalty/earning-rules/{id}

Update an existing earning rule

Permissions: 🟠 loyalty.update

Update earning rule › path Parameters

id

string · pattern: ^[0-9]+$ · required

Earning rule ID

Update earning rule › Request Body

name

string

description

string

ruleType

string · enum

Enum values:

SPEND_BASED

ITEM_BASED

VISIT_BASED

ACTION_BASED

isActive

boolean

minTierId

number

pointsPerCurrencyUnit

number

minPurchaseAmount

number

itemId

number

pointsMode

string · enum

Enum values:

FIXED

MULTIPLIER

pointsPerItem

number

pointsMultiplier

number

pointsPerVisit

number

minPurchaseForVisit

number

actionType

string

pointsPerAction

number

maxActionsPerPeriod

number

actionPeriod

string

validFrom

string | null · date

validUntil

string | null · date

priority

number

Update earning rule › Responses

Default Response

status

string · enum

Enum values:

success

object

PUT/api/v1/loyalty/earning-rules/{id}

curl --request PUT \
  --url https://common-api.karma.life/api/v1/loyalty/earning-rules/:id \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "name",
  "description": "description",
  "ruleType": "SPEND_BASED",
  "isActive": true,
  "minTierId": 0,
  "pointsPerCurrencyUnit": 0,
  "minPurchaseAmount": 0,
  "itemId": 0,
  "pointsMode": "FIXED",
  "pointsPerItem": 0,
  "pointsMultiplier": 0,
  "pointsPerVisit": 0,
  "minPurchaseForVisit": 0,
  "actionType": "actionType",
  "pointsPerAction": 0,
  "maxActionsPerPeriod": 0,
  "actionPeriod": "actionPeriod",
  "validFrom": "2024-08-25",
  "validUntil": "2024-08-25",
  "priority": 0
}
'

Example Request Body

{
  "name": "name",
  "description": "description",
  "ruleType": "SPEND_BASED",
  "isActive": true,
  "minTierId": 0,
  "pointsPerCurrencyUnit": 0,
  "minPurchaseAmount": 0,
  "itemId": 0,
  "pointsMode": "FIXED",
  "pointsPerItem": 0,
  "pointsMultiplier": 0,
  "pointsPerVisit": 0,
  "minPurchaseForVisit": 0,
  "actionType": "actionType",
  "pointsPerAction": 0,
  "maxActionsPerPeriod": 0,
  "actionPeriod": "actionPeriod",
  "validFrom": "2024-08-25",
  "validUntil": "2024-08-25",
  "priority": 0
}

Example Responses

No example specified for this content type

application/json

Delete earning rule

DELETE

https://common-api.karma.life

/api/v1/loyalty/earning-rules/{id}

Delete an earning rule

Permissions: 🔴 loyalty.delete

Delete earning rule › path Parameters

id

string · pattern: ^[0-9]+$ · required

Earning rule ID

Delete earning rule › Responses

Default Response

status

string · enum

Enum values:

success

object

DELETE/api/v1/loyalty/earning-rules/{id}

curl --request DELETE \
  --url https://common-api.karma.life/api/v1/loyalty/earning-rules/:id

Example Responses

No example specified for this content type

application/json

Enroll user in program

POST

https://common-api.karma.life

/api/v1/loyalty/enroll

Enroll a single user in a loyalty program. Supports userId, email, or phone identification.

Permissions: 🟢 loyalty.create

Enroll user in program › Request Body

programId

number · required

Loyalty program ID

userId

number

User ID (priority 1)

email

string · email

Email address (priority 2)

phone

string

Phone number (priority 3)

tierId

number

Optional tier ID to assign at enrollment (requires loyalty.tier.assign permission)

Enroll user in program › Responses

Default Response

status

string · enum

Enum values:

success

object

POST/api/v1/loyalty/enroll

curl --request POST \
  --url https://common-api.karma.life/api/v1/loyalty/enroll \
  --header 'Content-Type: application/json' \
  --data '
{
  "programId": 0,
  "userId": 0,
  "email": "test@example.com",
  "phone": "phone",
  "tierId": 0
}
'

Example Request Body

{
  "programId": 0,
  "userId": 0,
  "email": "test@example.com",
  "phone": "phone",
  "tierId": 0
}

Example Responses

No example specified for this content type

application/json

Bulk enroll users

POST

https://common-api.karma.life

/api/v1/loyalty/enroll/bulk

Enroll multiple users in a loyalty program at once. When tierId is provided, the tier is applied to ALL users (new and already-enrolled).

Permissions: 🟢 loyalty.create

Bulk enroll users › Request Body

programId

number · required

Loyalty program ID

userIds

number[] · required

Array of user IDs to enroll

tierId

number

Optional tier ID to assign to ALL users (requires loyalty.tier.assign permission)

Bulk enroll users › Responses

Default Response

status

string · enum

Enum values:

success

object

POST/api/v1/loyalty/enroll/bulk

curl --request POST \
  --url https://common-api.karma.life/api/v1/loyalty/enroll/bulk \
  --header 'Content-Type: application/json' \
  --data '
{
  "programId": 0,
  "userIds": [
    0
  ],
  "tierId": 0
}
'

Example Request Body

{
  "programId": 0,
  "userIds": [
    0
  ],
  "tierId": 0
}

Example Responses

No example specified for this content type

application/json

Award points

POST

https://common-api.karma.life

/api/v1/loyalty/points/award

Award points to a user manually. Used for promotional points, customer service adjustments, or manual corrections.

Permissions: 🟢 loyalty.create

Award points › Request Body

userId

number · required

User ID to award points to

loyaltyProgramId

number · required

Loyalty program ID

points

number · min: 1 · required

Number of points to award (must be positive)

description

string · required

Reason for awarding points

object

Optional metadata for tracking

Award points › Responses

Points awarded successfully

status

string · enum · required

Enum values:

success

object · required

POST/api/v1/loyalty/points/award

curl --request POST \
  --url https://common-api.karma.life/api/v1/loyalty/points/award \
  --header 'Content-Type: application/json' \
  --data '
{
  "userId": 0,
  "loyaltyProgramId": 0,
  "points": 1,
  "description": "description",
  "metadata": {}
}
'

Example Request Body

{
  "userId": 0,
  "loyaltyProgramId": 0,
  "points": 1,
  "description": "description",
  "metadata": {}
}

Example Responses

No example specified for this content type

application/json

Claim loyalty points for a past purchase

POST

https://common-api.karma.life

/api/v1/loyalty/points/claim-purchase

Retroactively claim loyalty points for a purchase made within the last 30 days.

Claim loyalty points for a past purchase › Request Body

userId

number · required

User ID of the loyalty program member

loyaltyProgramId

number · required

Loyalty program ID

purchaseIntentId

string · required

Purchase intent ID from the completed purchase

Claim loyalty points for a past purchase › Responses

Points claimed or no points to award

transactionId

string | null

pointsAwarded

number

message

string | null

createdAt

string | null

POST/api/v1/loyalty/points/claim-purchase

curl --request POST \
  --url https://common-api.karma.life/api/v1/loyalty/points/claim-purchase \
  --header 'Content-Type: application/json' \
  --data '
{
  "userId": 0,
  "loyaltyProgramId": 0,
  "purchaseIntentId": "purchaseIntentId"
}
'

Example Request Body

{
  "userId": 0,
  "loyaltyProgramId": 0,
  "purchaseIntentId": "purchaseIntentId"
}

Example Responses

No example specified for this content type

application/json

Deduct points

POST

https://common-api.karma.life

/api/v1/loyalty/points/deduct

Deduct points from a user. Used for manual adjustments or corrections. For redemptions, use the redemption endpoints.

Permissions: 🟢 loyalty.create

Deduct points › Request Body

userId

number · required

User ID to deduct points from

loyaltyProgramId

number · required

Loyalty program ID

points

number · min: 1 · required

Number of points to deduct (must be positive)

description

string · required

Reason for deducting points

object

Optional metadata for tracking

Deduct points › Responses

Points deducted successfully

status

string · enum · required

Enum values:

success

object · required

POST/api/v1/loyalty/points/deduct

curl --request POST \
  --url https://common-api.karma.life/api/v1/loyalty/points/deduct \
  --header 'Content-Type: application/json' \
  --data '
{
  "userId": 0,
  "loyaltyProgramId": 0,
  "points": 1,
  "description": "description",
  "metadata": {}
}
'

Example Request Body

{
  "userId": 0,
  "loyaltyProgramId": 0,
  "points": 1,
  "description": "description",
  "metadata": {}
}

Example Responses

No example specified for this content type

application/json

Estimate points for purchase

POST

https://common-api.karma.life

/api/v1/loyalty/points/estimate

Estimate points that would be earned from a purchase. Used to display earning preview at checkout before the purchase is committed. No authentication required - called from storefront.

Estimate points for purchase › Request Body

loyaltyProgramId

number · required

Loyalty program ID

purchaseAmountCents

number · min: 0 · required

Estimated purchase amount in cents

itemIds

number[]

Array of item IDs in the cart (for item-based earning rules)

userTierId

number | null

User tier ID for tier-specific multipliers (optional)

Estimate points for purchase › Responses

Points estimate calculated

status

string · enum · required

Enum values:

success

object · required

POST/api/v1/loyalty/points/estimate

curl --request POST \
  --url https://common-api.karma.life/api/v1/loyalty/points/estimate \
  --header 'Content-Type: application/json' \
  --data '
{
  "loyaltyProgramId": 0,
  "purchaseAmountCents": 0,
  "itemIds": [
    0
  ],
  "userTierId": 0
}
'

Example Request Body

{
  "loyaltyProgramId": 0,
  "purchaseAmountCents": 0,
  "itemIds": [
    0
  ],
  "userTierId": 0
}

Example Responses

No example specified for this content type

application/json

Process purchase points

POST

https://common-api.karma.life

/api/v1/loyalty/points/process-purchase

Process points from a purchase. Called after a purchase is completed to calculate and award earned points based on earning rules.

Permissions: 🟢 loyalty.create

Process purchase points › Request Body

userId

number · required

User ID who made the purchase

loyaltyProgramId

number · required

Loyalty program ID

purchaseId

number · required

Purchase ID to process

purchaseAmountCents

number · required

Total purchase amount in cents

itemIds

number[]

Array of item IDs in the purchase (for item-based earning rules)

Process purchase points › Responses

Purchase processed (no points earned)

status

string · enum · required

Enum values:

success

object · required

POST/api/v1/loyalty/points/process-purchase

curl --request POST \
  --url https://common-api.karma.life/api/v1/loyalty/points/process-purchase \
  --header 'Content-Type: application/json' \
  --data '
{
  "userId": 0,
  "loyaltyProgramId": 0,
  "purchaseId": 0,
  "purchaseAmountCents": 0,
  "itemIds": [
    0
  ]
}
'

Example Request Body

{
  "userId": 0,
  "loyaltyProgramId": 0,
  "purchaseId": 0,
  "purchaseAmountCents": 0,
  "itemIds": [
    0
  ]
}

Example Responses

No example specified for this content type

application/json

List loyalty programs

GET

https://common-api.karma.life

/api/v1/loyalty/programs

List loyalty programs with optional filtering

Permissions: 🔵 loyalty.read

List loyalty programs › query Parameters

locationId

number

Filter by location ID

isActive

boolean

Filter by active status

page

number · min: 1

Page number

Default: 1

limit

number · min: 1 · max: 1000

Items per page

Default: 50

List loyalty programs › Responses

Default Response

status

string · enum · required

Enum values:

success

object · required

GET/api/v1/loyalty/programs

curl --request GET \
  --url https://common-api.karma.life/api/v1/loyalty/programs

Example Responses

No example specified for this content type

application/json

Create loyalty program

POST

https://common-api.karma.life

/api/v1/loyalty/programs

Create a new loyalty program

Permissions: 🟢 loyalty.create

Create loyalty program › Request Body

name

string · minLength: 1 · required

Program name

description

string | null

Program description

currency

string

Currency code

Default: SEK

isActive

boolean

Whether program is active

Default: true

startDate

string | null · date

Program start date

endDate

string | null · date

Program end date

loyaltyCardImage

string | null

Loyalty card image URL

loyaltyColor

string | null

Loyalty card color (hex)

Create loyalty program › Responses

Default Response

status

string · enum

Enum values:

success

object

POST/api/v1/loyalty/programs

curl --request POST \
  --url https://common-api.karma.life/api/v1/loyalty/programs \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "name",
  "description": "description",
  "currency": "SEK",
  "isActive": true,
  "startDate": "2024-08-25",
  "endDate": "2024-08-25",
  "loyaltyCardImage": "loyaltyCardImage",
  "loyaltyColor": "loyaltyColor"
}
'

Example Request Body

{
  "name": "name",
  "description": "description",
  "currency": "SEK",
  "isActive": true,
  "startDate": "2024-08-25",
  "endDate": "2024-08-25",
  "loyaltyCardImage": "loyaltyCardImage",
  "loyaltyColor": "loyaltyColor"
}

Example Responses

No example specified for this content type

application/json

Get loyalty program

GET

https://common-api.karma.life

/api/v1/loyalty/programs/{id}

Get a single loyalty program by ID

Permissions: 🔵 loyalty.read

Get loyalty program › path Parameters

id

string · pattern: ^[0-9]+$ · required

Loyalty program ID

Get loyalty program › Responses

Default Response

status

string · enum

Enum values:

success

object

GET/api/v1/loyalty/programs/{id}

curl --request GET \
  --url https://common-api.karma.life/api/v1/loyalty/programs/:id

Example Responses

No example specified for this content type

application/json

Update loyalty program

PUT

https://common-api.karma.life

/api/v1/loyalty/programs/{id}

Update an existing loyalty program

Permissions: 🟠 loyalty.update

Update loyalty program › path Parameters

id

string · pattern: ^[0-9]+$ · required

Loyalty program ID

Update loyalty program › Request Body

name

string

Program name

description

string | null

Program description

currency

string

Currency code

isActive

boolean

Whether program is active

startDate

string | null · date

Program start date

endDate

string | null · date

Program end date

loyaltyCardImage

string | null

Loyalty card image URL

loyaltyColor

string | null

Loyalty card color (hex)

Update loyalty program › Responses

Default Response

status

string · enum

Enum values:

success

object

PUT/api/v1/loyalty/programs/{id}

curl --request PUT \
  --url https://common-api.karma.life/api/v1/loyalty/programs/:id \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "name",
  "description": "description",
  "currency": "currency",
  "isActive": true,
  "startDate": "2024-08-25",
  "endDate": "2024-08-25",
  "loyaltyCardImage": "loyaltyCardImage",
  "loyaltyColor": "loyaltyColor"
}
'

Example Request Body

{
  "name": "name",
  "description": "description",
  "currency": "currency",
  "isActive": true,
  "startDate": "2024-08-25",
  "endDate": "2024-08-25",
  "loyaltyCardImage": "loyaltyCardImage",
  "loyaltyColor": "loyaltyColor"
}

Example Responses

No example specified for this content type

application/json

Delete loyalty program

DELETE

https://common-api.karma.life

/api/v1/loyalty/programs/{id}

Soft-delete a loyalty program (sets deleted_at, preserves data). Requires loyalty.admin permission.

Permissions: ⚪ loyalty.admin

Delete loyalty program › path Parameters

id

string · pattern: ^[0-9]+$ · required

Loyalty program ID

Delete loyalty program › Responses

Program soft-deleted successfully

No data returned

DELETE/api/v1/loyalty/programs/{id}

curl --request DELETE \
  --url https://common-api.karma.life/api/v1/loyalty/programs/:id

Example Responses

No example specified for this content type

List points accounts

GET

https://common-api.karma.life

/api/v1/loyalty/programs/{programId}/accounts

Get all points accounts for a loyalty program with pagination

Permissions: 🔵 loyalty.read

List points accounts › path Parameters

programId

string · pattern: ^[0-9]+$ · required

Loyalty program ID

List points accounts › query Parameters

page

number · min: 1

Page number

Default: 1

limit

number · min: 1 · max: 1000

Items per page

Default: 50

List points accounts › Responses

Default Response

status

string · enum

Enum values:

success

object

GET/api/v1/loyalty/programs/{programId}/accounts

curl --request GET \
  --url https://common-api.karma.life/api/v1/loyalty/programs/:programId/accounts

Example Responses

No example specified for this content type

application/json

List earning rules

GET

https://common-api.karma.life

/api/v1/loyalty/programs/{programId}/earning-rules

Get all earning rules for a loyalty program

Permissions: 🔵 loyalty.read

List earning rules › path Parameters

programId

string · pattern: ^[0-9]+$ · required

Loyalty program ID

List earning rules › Responses

Default Response

status

string · enum

Enum values:

success

object

GET/api/v1/loyalty/programs/{programId}/earning-rules

curl --request GET \
  --url https://common-api.karma.life/api/v1/loyalty/programs/:programId/earning-rules

Example Responses

No example specified for this content type

application/json

List rewards catalog

GET

https://common-api.karma.life

/api/v1/loyalty/programs/{programId}/rewards

Get the rewards catalog for a loyalty program

Permissions: 🔵 loyalty.read

List rewards catalog › path Parameters

programId

string · pattern: ^[0-9]+$ · required

Loyalty program ID

List rewards catalog › query Parameters

userId

string · pattern: ^[0-9]+$

Optional user ID. When provided, rewards the user has already hit their max_redemptions_per_user for are filtered out.

List rewards catalog › Responses

Default Response

status

string · enum

Enum values:

success

object

GET/api/v1/loyalty/programs/{programId}/rewards

curl --request GET \
  --url https://common-api.karma.life/api/v1/loyalty/programs/:programId/rewards

Example Responses

No example specified for this content type

application/json

List loyalty tiers

GET

https://common-api.karma.life

/api/v1/loyalty/programs/{programId}/tiers

Get all tiers for a loyalty program

Permissions: 🔵 loyalty.read

List loyalty tiers › path Parameters

programId

string · pattern: ^[0-9]+$ · required

Loyalty program ID

List loyalty tiers › Responses

Default Response

status

string · enum

Enum values:

success

object

GET/api/v1/loyalty/programs/{programId}/tiers

curl --request GET \
  --url https://common-api.karma.life/api/v1/loyalty/programs/:programId/tiers

Example Responses

No example specified for this content type

application/json

Get user points account

GET

https://common-api.karma.life

/api/v1/loyalty/programs/{programId}/users/{userId}/account

Get or create a points account for a specific user in a loyalty program

Permissions: 🔵 loyalty.read

Get user points account › path Parameters

programId

string · pattern: ^[0-9]+$ · required

Loyalty program ID

userId

string · pattern: ^[0-9]+$ · required

User ID

Get user points account › Responses

Default Response

status

string · enum

Enum values:

success

object

GET/api/v1/loyalty/programs/{programId}/users/{userId}/account

curl --request GET \
  --url https://common-api.karma.life/api/v1/loyalty/programs/:programId/users/:userId/account

Example Responses

No example specified for this content type

application/json

Get user redemptions

GET

https://common-api.karma.life

/api/v1/loyalty/programs/{programId}/users/{userId}/redemptions

Get reward redemption history for a user in a loyalty program

Permissions: 🔵 loyalty.read

Get user redemptions › path Parameters

programId

string · pattern: ^[0-9]+$ · required

Loyalty program ID

userId

string · pattern: ^[0-9]+$ · required

User ID

Get user redemptions › Responses

Default Response

status

string · enum

Enum values:

success

object

GET/api/v1/loyalty/programs/{programId}/users/{userId}/redemptions

curl --request GET \
  --url https://common-api.karma.life/api/v1/loyalty/programs/:programId/users/:userId/redemptions

Example Responses

No example specified for this content type

application/json

Create reward

POST

https://common-api.karma.life

/api/v1/loyalty/rewards

Create a new reward in the catalog

Permissions: 🟢 loyalty.create

Create reward › Request Body

loyaltyProgramId

number · required

name

string · minLength: 1 · required

pointsCost

number · min: 1 · required

discountId

number · required

description

string

minTierId

number

isActive

boolean

Default: true

stockQuantity

number

maxRedemptionsPerUser

number

availableFrom

string | null · date

availableUntil

string | null · date

displayOrder

number

Default: 0

expirationDays

number

Create reward › Responses

Default Response

status

string · enum

Enum values:

success

object

POST/api/v1/loyalty/rewards

curl --request POST \
  --url https://common-api.karma.life/api/v1/loyalty/rewards \
  --header 'Content-Type: application/json' \
  --data '
{
  "loyaltyProgramId": 0,
  "name": "name",
  "description": "description",
  "pointsCost": 1,
  "minTierId": 0,
  "discountId": 0,
  "isActive": true,
  "stockQuantity": 0,
  "maxRedemptionsPerUser": 0,
  "availableFrom": "2024-08-25",
  "availableUntil": "2024-08-25",
  "displayOrder": 0,
  "expirationDays": 0
}
'

Example Request Body

{
  "loyaltyProgramId": 0,
  "name": "name",
  "description": "description",
  "pointsCost": 1,
  "minTierId": 0,
  "discountId": 0,
  "isActive": true,
  "stockQuantity": 0,
  "maxRedemptionsPerUser": 0,
  "availableFrom": "2024-08-25",
  "availableUntil": "2024-08-25",
  "displayOrder": 0,
  "expirationDays": 0
}

Example Responses

No example specified for this content type

application/json

Update reward

PUT

https://common-api.karma.life

/api/v1/loyalty/rewards/{id}

Update an existing reward in the catalog

Permissions: 🟠 loyalty.update

Update reward › path Parameters

id

string · pattern: ^[0-9]+$ · required

Reward ID

Update reward › Request Body

name

string

description

string

pointsCost

number · min: 1

minTierId

number

discountId

number

isActive

boolean

stockQuantity

number

maxRedemptionsPerUser

number

availableFrom

string | null · date

availableUntil

string | null · date

displayOrder

number

expirationDays

number

Update reward › Responses

Default Response

status

string · enum

Enum values:

success

object

PUT/api/v1/loyalty/rewards/{id}

curl --request PUT \
  --url https://common-api.karma.life/api/v1/loyalty/rewards/:id \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "name",
  "description": "description",
  "pointsCost": 1,
  "minTierId": 0,
  "discountId": 0,
  "isActive": true,
  "stockQuantity": 0,
  "maxRedemptionsPerUser": 0,
  "availableFrom": "2024-08-25",
  "availableUntil": "2024-08-25",
  "displayOrder": 0,
  "expirationDays": 0
}
'

Example Request Body

{
  "name": "name",
  "description": "description",
  "pointsCost": 1,
  "minTierId": 0,
  "discountId": 0,
  "isActive": true,
  "stockQuantity": 0,
  "maxRedemptionsPerUser": 0,
  "availableFrom": "2024-08-25",
  "availableUntil": "2024-08-25",
  "displayOrder": 0,
  "expirationDays": 0
}

Example Responses

No example specified for this content type

application/json

Delete reward

DELETE

https://common-api.karma.life

/api/v1/loyalty/rewards/{id}

Delete a reward from the catalog

Permissions: 🔴 loyalty.delete

Delete reward › path Parameters

id

string · pattern: ^[0-9]+$ · required

Reward ID

Delete reward › Responses

Default Response

status

string · enum

Enum values:

success

object

DELETE/api/v1/loyalty/rewards/{id}

curl --request DELETE \
  --url https://common-api.karma.life/api/v1/loyalty/rewards/:id

Example Responses

No example specified for this content type

application/json

Create loyalty tier

POST

https://common-api.karma.life

/api/v1/loyalty/tiers

Create a new tier for a loyalty program

Permissions: 🟢 loyalty.create

Create loyalty tier › Request Body

loyaltyProgramId

number · required

name

string · minLength: 1 · required

description

string | null

pointsThreshold

number · min: 0

thresholdType

string · enum

Enum values:

LIFETIME_POINTS

ROLLING_PERIOD

MANUAL

Default: LIFETIME_POINTS

rollingPeriodMonths

number | null · min: 1

Required when thresholdType = ROLLING_PERIOD

tierCardImageUrl

string | null

Tier card image URL

tierColor

string | null

Tier card color (hex)

order

number

Default: 0

Create loyalty tier › Responses

Default Response

status

string · enum

Enum values:

success

object

POST/api/v1/loyalty/tiers

curl --request POST \
  --url https://common-api.karma.life/api/v1/loyalty/tiers \
  --header 'Content-Type: application/json' \
  --data '
{
  "loyaltyProgramId": 0,
  "name": "name",
  "description": "description",
  "pointsThreshold": 0,
  "thresholdType": "LIFETIME_POINTS",
  "rollingPeriodMonths": 1,
  "tierCardImageUrl": "tierCardImageUrl",
  "tierColor": "tierColor",
  "order": 0
}
'

Example Request Body

{
  "loyaltyProgramId": 0,
  "name": "name",
  "description": "description",
  "pointsThreshold": 0,
  "thresholdType": "LIFETIME_POINTS",
  "rollingPeriodMonths": 1,
  "tierCardImageUrl": "tierCardImageUrl",
  "tierColor": "tierColor",
  "order": 0
}

Example Responses

No example specified for this content type

application/json

Update loyalty tier

PUT

https://common-api.karma.life

/api/v1/loyalty/tiers/{id}

Update an existing loyalty tier

Permissions: 🟠 loyalty.update

Update loyalty tier › path Parameters

id

string · pattern: ^[0-9]+$ · required

Tier ID

Update loyalty tier › Request Body

name

string

Tier name

description

string | null

Tier description

pointsThreshold

number · min: 0

Points required for this tier

thresholdType

string · enum

Enum values:

LIFETIME_POINTS

ROLLING_PERIOD

MANUAL

rollingPeriodMonths

number | null · min: 1

tierCardImageUrl

string | null

Tier card image URL

tierColor

string | null

Tier card color (hex)

order

number

Update loyalty tier › Responses

Default Response

status

string · enum

Enum values:

success

object

PUT/api/v1/loyalty/tiers/{id}

curl --request PUT \
  --url https://common-api.karma.life/api/v1/loyalty/tiers/:id \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "name",
  "description": "description",
  "pointsThreshold": 0,
  "thresholdType": "LIFETIME_POINTS",
  "rollingPeriodMonths": 1,
  "tierCardImageUrl": "tierCardImageUrl",
  "tierColor": "tierColor",
  "order": 0
}
'

Example Request Body

{
  "name": "name",
  "description": "description",
  "pointsThreshold": 0,
  "thresholdType": "LIFETIME_POINTS",
  "rollingPeriodMonths": 1,
  "tierCardImageUrl": "tierCardImageUrl",
  "tierColor": "tierColor",
  "order": 0
}

Example Responses

No example specified for this content type

application/json

Delete loyalty tier

DELETE

https://common-api.karma.life

/api/v1/loyalty/tiers/{id}

Delete a loyalty tier

Permissions: 🔴 loyalty.delete

Delete loyalty tier › path Parameters

id

string · pattern: ^[0-9]+$ · required

Tier ID

Delete loyalty tier › Responses

Default Response

status

string · enum

Enum values:

success

object

DELETE/api/v1/loyalty/tiers/{id}

curl --request DELETE \
  --url https://common-api.karma.life/api/v1/loyalty/tiers/:id

Example Responses

No example specified for this content type

application/json

List points transactions

GET

https://common-api.karma.life

/api/v1/loyalty/transactions

Get points transactions with optional filters (account, user, type, date range)

Permissions: 🔵 loyalty.read

List points transactions › query Parameters

pointsAccountId

number

Filter by points account ID

programId

number

Filter by loyalty program ID

userId

number

Filter by user ID

transactionType

string

Filter by transaction type

startDate

string · date

Filter by start date

endDate

string · date

Filter by end date

page

number · min: 1

Default: 1

limit

number · min: 1 · max: 1000

Default: 50

List points transactions › Responses

Default Response

status

string · enum

Enum values:

success

object

GET/api/v1/loyalty/transactions

curl --request GET \
  --url https://common-api.karma.life/api/v1/loyalty/transactions

Example Responses

No example specified for this content type

application/json

Get user enrolled programs

GET

https://common-api.karma.life

/api/v1/loyalty/users/{userId}/programs

Get all loyalty programs a user is enrolled in with account details and current tier. Users can only view their own enrollments. API keys with 'loyalty.read' permission can view any user's enrollments.

Permissions: 🔵 loyalty.read

Get user enrolled programs › path Parameters

userId

string · pattern: ^[0-9]+$ · required

User ID

Get user enrolled programs › Responses

Default Response

status

string · enum · required

Enum values:

success

object · required

GET/api/v1/loyalty/users/{userId}/programs

curl --request GET \
  --url https://common-api.karma.life/api/v1/loyalty/users/:userId/programs

Example Responses

No example specified for this content type

application/json

Validate loyalty members

POST

https://common-api.karma.life

/api/v1/loyalty/validate

Validate loyalty membership for multiple users by userId, email, phone, or cardId

Validate loyalty members › Request Body

object[] · required

Array of user identifiers to validate

Validate loyalty members › Responses

Loyalty validation results

status

string · enum · required

Enum values:

success

object · required

POST/api/v1/loyalty/validate

curl --request POST \
  --url https://common-api.karma.life/api/v1/loyalty/validate \
  --header 'Content-Type: application/json' \
  --data '
{
  "users": [
    {
      "userId": 0,
      "email": "email",
      "phone": "phone",
      "cardId": "cardId"
    }
  ]
}
'

Example Request Body

{
  "users": [
    {
      "userId": 0,
      "email": "email",
      "phone": "phone",
      "cardId": "cardId"
    }
  ]
}

Example Responses

No example specified for this content type

application/json

Webhook: Loyalty identification (post-payment)

POST

https://common-api.karma.life

/webhook/loyalty.identify

Fired after payment completion when a loyalty identification opportunity exists. Discriminated union on scenario. Fire-and-forget — never throws.

This is an outbound webhook event. Karma POSTs this payload to the URL you registered via POST /api/v1/webhooks/subscriptions. Your endpoint should respond 2xx within 30 seconds to acknowledge delivery.

Webhook: Loyalty identification (post-payment) › Request Body

Standard envelope wrapping every outbound webhook event.

id

string · required

Unique webhook delivery ID

event

string · enum · required

Enum values:

loyalty.identify

resource

string · enum · required

Enum values:

loyalty

resourceId

string · required

String ID of the affected resource

timestamp

string · date-time · required

ISO 8601 timestamp when the event was emitted

apiVersion

string · enum · required

Enum values:

Webhook: Loyalty identification (post-payment) › Responses

200

Acknowledged. Karma considers any 2xx response a successful delivery; non-2xx triggers retry with exponential backoff.

No data returned

POST/webhook/loyalty.identify

curl --request POST \
  --url https://common-api.karma.life/webhook/loyalty.identify \
  --header 'Content-Type: application/json' \
  --data '
{
  "id": "evt_01HZK3...",
  "event": "loyalty.identify",
  "resource": "loyalty",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "scenario": "POINTS_EARNED",
    "purchaseIntentId": "00000000-0000-0000-0000-000000000000",
    "locationId": 0,
    "member": {
      "firstName": "firstName",
      "tier": "tier",
      "pointsEarned": 0,
      "currentBalance": 0
    }
  }
}
'

Example Request Body

{
  "id": "evt_01HZK3...",
  "event": "loyalty.identify",
  "resource": "loyalty",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "scenario": "POINTS_EARNED",
    "purchaseIntentId": "00000000-0000-0000-0000-000000000000",
    "locationId": 0,
    "member": {
      "firstName": "firstName",
      "tier": "tier",
      "pointsEarned": 0,
      "currentBalance": 0
    }
  }
}

Example Responses

No example specified for this content type

Webhook: Loyalty program member joined

POST

https://common-api.karma.life

/webhook/loyalty.member_joined

Fired when a user enrolls in a loyalty program. Used to trigger drip campaigns.

Webhook: Loyalty program member joined › Request Body

Standard envelope wrapping every outbound webhook event.

id

string · required

Unique webhook delivery ID

event

string · enum · required

Enum values:

loyalty.member_joined

resource

string · enum · required

Enum values:

loyalty

resourceId

string · required

String ID of the affected resource

timestamp

string · date-time · required

ISO 8601 timestamp when the event was emitted

apiVersion

string · enum · required

Enum values:

object

Webhook: Loyalty program member joined › Responses

200

Acknowledged. Karma considers any 2xx response a successful delivery; non-2xx triggers retry with exponential backoff.

No data returned

POST/webhook/loyalty.member_joined

curl --request POST \
  --url https://common-api.karma.life/webhook/loyalty.member_joined \
  --header 'Content-Type: application/json' \
  --data '
{
  "id": "evt_01HZK3...",
  "event": "loyalty.member_joined",
  "resource": "loyalty",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "userId": 0,
    "locationId": 0,
    "programId": 0
  }
}
'

Example Request Body

{
  "id": "evt_01HZK3...",
  "event": "loyalty.member_joined",
  "resource": "loyalty",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "userId": 0,
    "locationId": 0,
    "programId": 0
  }
}

Example Responses

No example specified for this content type

Webhook: Loyalty member tier changed

POST

https://common-api.karma.life

/webhook/loyalty.tier_changed

Fired on promotion or demotion. previousTierId is null on first tier assignment.

Webhook: Loyalty member tier changed › Request Body

Standard envelope wrapping every outbound webhook event.

id

string · required

Unique webhook delivery ID

event

string · enum · required

Enum values:

loyalty.tier_changed

resource

string · enum · required

Enum values:

loyalty

resourceId

string · required

String ID of the affected resource

timestamp

string · date-time · required

ISO 8601 timestamp when the event was emitted

apiVersion

string · enum · required

Enum values:

object

Webhook: Loyalty member tier changed › Responses

200

Acknowledged. Karma considers any 2xx response a successful delivery; non-2xx triggers retry with exponential backoff.

No data returned

POST/webhook/loyalty.tier_changed

curl --request POST \
  --url https://common-api.karma.life/webhook/loyalty.tier_changed \
  --header 'Content-Type: application/json' \
  --data '
{
  "id": "evt_01HZK3...",
  "event": "loyalty.tier_changed",
  "resource": "loyalty",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "userId": 0,
    "locationId": 0,
    "programId": 0,
    "previousTierId": 0,
    "newTierId": 0
  }
}
'

Example Request Body

{
  "id": "evt_01HZK3...",
  "event": "loyalty.tier_changed",
  "resource": "loyalty",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "userId": 0,
    "locationId": 0,
    "programId": 0,
    "previousTierId": 0,
    "newTierId": 0
  }
}

Example Responses

No example specified for this content type

Webhook: Loyalty points awarded for purchase

POST

https://common-api.karma.life

/webhook/loyalty.purchase.updated

Fired whenever points are awarded for a purchase — automatic post-payment, retroactive guest claim, or staff-linked. Storefront confirmation page subscribes via Ably to reflect "Processing…" → real points.

Webhook: Loyalty points awarded for purchase › Request Body

Standard envelope wrapping every outbound webhook event.

id

string · required

Unique webhook delivery ID

event

string · enum · required

Enum values:

loyalty.purchase.updated

resource

string · enum · required

Enum values:

loyalty

resourceId

string · required

String ID of the affected resource

timestamp

string · date-time · required

ISO 8601 timestamp when the event was emitted

apiVersion

string · enum · required

Enum values:

object

Webhook: Loyalty points awarded for purchase › Responses

200

Acknowledged. Karma considers any 2xx response a successful delivery; non-2xx triggers retry with exponential backoff.

No data returned

POST/webhook/loyalty.purchase.updated

curl --request POST \
  --url https://common-api.karma.life/webhook/loyalty.purchase.updated \
  --header 'Content-Type: application/json' \
  --data '
{
  "id": "evt_01HZK3...",
  "event": "loyalty.purchase.updated",
  "resource": "loyalty",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "purchaseIntentId": "00000000-0000-0000-0000-000000000000",
    "locationId": 0,
    "pointsAwarded": 0,
    "userId": 0
  }
}
'

Example Request Body

{
  "id": "evt_01HZK3...",
  "event": "loyalty.purchase.updated",
  "resource": "loyalty",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "purchaseIntentId": "00000000-0000-0000-0000-000000000000",
    "locationId": 0,
    "pointsAwarded": 0,
    "userId": 0
  }
}

Example Responses

No example specified for this content type

Locations Menu Layouts