Rewards

The Rewards API allows you to create and manage rewards that users can earn through campaigns, challenges, and other loyalty mechanics. Rewards can grant points, products, competition entries, or unique/non-unique coupons.

Overview

Reward Types:

points: Award loyalty points
product: Grant a specific product
competition_entry: Add competition entries
unique_coupon: Issue a unique coupon from a code pool
non_unique_coupon: Issue a reusable coupon code

Key Features:

Flexible reward configuration based on type
Manual reward grants to individual users
Status management (active/inactive)
Integration with campaigns and rules

Endpoints

List Rewards

Get a list of rewards for your organization.

GET /v1/rewards

Query Parameters:

Parameter

Type

Required

Description

status

string

Filter by status: active, inactive

rewardType

string

Filter by type: points, product, competition_entry, unique_coupon, non_unique_coupon

Example Request:

curl -X GET "https://api.monterosa.cloud/loyalty/v1/rewards?status=active" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Monterosa-Org-ID: YOUR_ORG_UUID"

Example Response:

{
  "success": true,
  "data": {
    "rewards": [
      {
        "orgId": "550e8400-e29b-41d4-a716-446655440000",
        "rewardId": "rew_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "Daily Check-in Points",
        "description": "Reward for daily check-ins",
        "rewardType": "points",
        "status": "active",
        "config": {
          "amount": 10
        },
        "metadata": {},
        "createdAt": "2025-10-01T10:00:00.000Z",
        "updatedAt": "2025-10-01T10:00:00.000Z"
      },
      {
        "orgId": "550e8400-e29b-41d4-a716-446655440000",
        "rewardId": "rew_b2c3d4e5-f6g7-8901-bcde-fg2345678901",
        "name": "VIP Badge Reward",
        "description": "Grant VIP badge to users",
        "rewardType": "product",
        "status": "active",
        "config": {
          "productId": "prod_vip_badge_001",
          "quantity": 1
        },
        "metadata": {},
        "createdAt": "2025-10-05T14:30:00.000Z",
        "updatedAt": "2025-10-05T14:30:00.000Z"
      }
    ],
    "count": 2
  }
}

Create Reward

Create a new reward with type-specific configuration.

POST /v1/rewards

Request Body:

Field

Type

Required

Description

name

string

Yes

Reward name

rewardType

string

Yes

Reward type: points, product, competition_entry, unique_coupon, non_unique_coupon

config

object

Yes

Type-specific configuration (see below)

description

string

Reward description

status

string

Status: active, inactive (default: active)

metadata

object

Additional metadata

Config by Reward Type:

Points Reward Config

{
  "amount": 100
}

amount (required): Number of points to award (positive number)

Product Reward Config

{
  "productId": "prod_abc123",
  "quantity": 1
}

productId (required): Product ID to grant
quantity (optional): Number of items to grant (default: 1)

Competition Entry Config

{
  "competitionId": "comp_abc123",
  "entries": 5
}

competitionId (required): Competition ID
entries (optional): Number of entries to grant (default: 1)

Unique Coupon Config

{
  "codePoolId": "pool_abc123"
}

codePoolId (required): Code pool ID to draw codes from

Non-Unique Coupon Config

{
  "code": "SAVE20",
  "discountType": "percentage",
  "discountValue": 20
}

code (required): Coupon code
discountType (required): percentage or fixed
discountValue (required): Discount amount (non-negative number)

Example Request (Points Reward):

curl -X POST "https://api.monterosa.cloud/loyalty/v1/rewards" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Monterosa-Org-ID: YOUR_ORG_UUID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Video Watch Reward",
    "description": "Points for watching videos",
    "rewardType": "points",
    "config": {
      "amount": 50
    },
    "status": "active"
  }'

Example Request (Product Reward):

curl -X POST "https://api.monterosa.cloud/loyalty/v1/rewards" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Monterosa-Org-ID: YOUR_ORG_UUID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Achievement Badge",
    "description": "Special achievement badge",
    "rewardType": "product",
    "config": {
      "productId": "prod_badge_achievement_001",
      "quantity": 1
    }
  }'

Example Response:

{
  "success": true,
  "data": {
    "message": "Reward created successfully",
    "reward": {
      "orgId": "550e8400-e29b-41d4-a716-446655440000",
      "rewardId": "rew_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Video Watch Reward",
      "description": "Points for watching videos",
      "rewardType": "points",
      "config": {
        "amount": 50
      },
      "status": "active",
      "metadata": {},
      "createdAt": "2025-10-11T10:00:00.000Z",
      "updatedAt": "2025-10-11T10:00:00.000Z",
      "orgStatusKey": "550e8400-e29b-41d4-a716-446655440000#active"
    }
  }
}

Get Reward

Retrieve a specific reward by ID.

GET /v1/rewards/{rewardId}

Path Parameters:

Parameter

Type

Required

Description

rewardId

string

Yes

Reward ID

Example Request:

curl -X GET "https://api.monterosa.cloud/loyalty/v1/rewards/rew_a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Monterosa-Org-ID: YOUR_ORG_UUID"

Example Response:

{
  "success": true,
  "data": {
    "orgId": "550e8400-e29b-41d4-a716-446655440000",
    "rewardId": "rew_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Video Watch Reward",
    "description": "Points for watching videos",
    "rewardType": "points",
    "config": {
      "amount": 50
    },
    "status": "active",
    "metadata": {},
    "createdAt": "2025-10-11T10:00:00.000Z",
    "updatedAt": "2025-10-11T10:00:00.000Z"
  }
}

Update Reward

Update an existing reward.

PUT /v1/rewards/{rewardId}

Path Parameters:

Parameter

Type

Required

Description

rewardId

string

Yes

Reward ID

Request Body: Any fields from Create Reward (except rewardType)

Example Request:

curl -X PUT "https://api.monterosa.cloud/loyalty/v1/rewards/rew_a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Monterosa-Org-ID: YOUR_ORG_UUID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Video Reward",
    "config": {
      "amount": 100
    },
    "status": "active"
  }'

Example Response:

{
  "success": true,
  "data": {
    "orgId": "550e8400-e29b-41d4-a716-446655440000",
    "rewardId": "rew_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Premium Video Reward",
    "rewardType": "points",
    "config": {
      "amount": 100
    },
    "status": "active",
    "updatedAt": "2025-10-11T11:00:00.000Z"
  }
}

Delete Reward

Delete a reward.

DELETE /v1/rewards/{rewardId}

Path Parameters:

Parameter

Type

Required

Description

rewardId

string

Yes

Reward ID

Example Request:

curl -X DELETE "https://api.monterosa.cloud/loyalty/v1/rewards/rew_a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Monterosa-Org-ID: YOUR_ORG_UUID"

Example Response:

{
  "success": true,
  "data": {
    "message": "Reward deleted successfully"
  }
}

Grant Reward

Manually grant a reward to a specific user. This bypasses campaign rules and immediately grants the reward.

POST /v1/rewards/grant

Request Body:

Field

Type

Required

Description

rewardId

string

Yes

Reward ID to grant

userId

string

Yes

User ID to receive the reward

metadata

object

Additional context (e.g., reason for grant)

Example Request:

curl -X POST "https://api.monterosa.cloud/loyalty/v1/rewards/grant" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Monterosa-Org-ID: YOUR_ORG_UUID" \
  -H "Content-Type: application/json" \
  -d '{
    "rewardId": "rew_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "userId": "user_123",
    "metadata": {
      "reason": "Customer service recovery",
      "ticketId": "TICKET-456"
    }
  }'

Example Response:

{
  "success": true,
  "data": {
    "message": "Reward granted successfully",
    "result": {
      "userId": "user_123",
      "rewardId": "rew_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "rewardType": "points",
      "transactionId": "txn_xyz789",
      "amount": 50,
      "campaignId": "manual_grant",
      "grantedAt": "2025-10-11T12:00:00.000Z"
    }
  }
}

Reward Type Examples

1. Points Reward

Award loyalty points to users.

{
  "name": "Quiz Completion Bonus",
  "rewardType": "points",
  "config": {
    "amount": 100
  },
  "description": "Bonus points for completing quiz"
}

2. Product Reward

Grant a specific product (badge, merchandise, etc.).

{
  "name": "First Place Badge",
  "rewardType": "product",
  "config": {
    "productId": "prod_badge_first_place",
    "quantity": 1
  },
  "description": "Badge for winning first place"
}

3. Competition Entry Reward

Grant entries to a competition or sweepstakes.

{
  "name": "Grand Prize Entries",
  "rewardType": "competition_entry",
  "config": {
    "competitionId": "comp_grand_prize_2025",
    "entries": 5
  },
  "description": "5 entries to the grand prize draw"
}

4. Unique Coupon Reward

Issue a unique coupon code from a code pool (one per user).

{
  "name": "Exclusive Discount Code",
  "rewardType": "unique_coupon",
  "config": {
    "codePoolId": "pool_exclusive_discount"
  },
  "description": "Unique 20% discount code"
}

5. Non-Unique Coupon Reward

Issue a reusable coupon code (same code for all users).

{
  "name": "Welcome Discount",
  "rewardType": "non_unique_coupon",
  "config": {
    "code": "WELCOME20",
    "discountType": "percentage",
    "discountValue": 20
  },
  "description": "20% welcome discount for new users"
}

Use Cases

1. Campaign Integration

Rewards are typically granted through campaigns:

{
  "name": "Video Watch Campaign",
  "type": "Reward",
  "triggers": [{
    "eventType": "user.video_watched",
    "conditions": {}
  }],
  "effects": [{
    "type": "grant_reward",
    "rewardId": "rew_video_points"
  }]
}

2. Manual Customer Service Grant

Use the grant endpoint to manually reward users:

# Grant bonus points for customer service recovery
curl -X POST .../v1/rewards/grant \
  -d '{
    "rewardId": "rew_bonus_points",
    "userId": "user_123",
    "metadata": {
      "reason": "Apology for service disruption",
      "ticketId": "CS-789"
    }
  }'

3. Progressive Rewards

Create tiered rewards for different achievement levels:

[
  {
    "name": "Bronze Achievement",
    "rewardType": "points",
    "config": { "amount": 100 }
  },
  {
    "name": "Silver Achievement",
    "rewardType": "points",
    "config": { "amount": 500 }
  },
  {
    "name": "Gold Achievement",
    "rewardType": "product",
    "config": {
      "productId": "prod_gold_badge",
      "quantity": 1
    }
  }
]

Validation Rules

Points Reward

amount must be a positive number

Product Reward

productId must reference an existing product
quantity must be a positive number (if provided)

Competition Entry Reward

competitionId must reference an existing competition
entries must be a positive number (if provided)

Unique Coupon Reward

codePoolId must reference an existing code pool with available codes

Non-Unique Coupon Reward

code must be a non-empty string
discountType must be percentage or fixed
discountValue must be a non-negative number

Error Responses

400 Bad Request

{
  "success": false,
  "error": {
    "message": "Missing required fields: name, rewardType, config"
  }
}

400 Invalid Config

{
  "success": false,
  "error": {
    "message": "Config for points reward must include amount (positive number)"
  }
}

404 Not Found

{
  "success": false,
  "error": {
    "message": "Reward not found"
  }
}

409 Conflict

{
  "success": false,
  "error": {
    "message": "Reward with this ID already exists"
  }
}

500 Internal Server Error

{
  "success": false,
  "error": {
    "message": "Failed to grant reward"
  }
}

Best Practices

Descriptive Names: Use clear reward names that indicate what users receive
Status Management: Use inactive status to temporarily disable rewards without deletion
Metadata: Store additional context in metadata for tracking and analytics
Validation: Always validate reward configuration before creation
Manual Grants: Use manual grants sparingly and document reasons in metadata
Product Availability: Ensure products have sufficient stock before creating product rewards

Campaigns API - Configure campaigns that grant rewards
Products API - Manage products used in product rewards
Transactions API - Track reward redemptions and grants

Support

For questions about the Rewards API:

Documentation: https://products.monterosa.co/mic/reference
Support: [email protected]

Last updated 26 days ago

Overview

Endpoints

List Rewards

Create Reward

Points Reward Config

Product Reward Config

Competition Entry Config

Unique Coupon Config

Non-Unique Coupon Config

Get Reward

Update Reward

Delete Reward

Grant Reward

Reward Type Examples

1. Points Reward

2. Product Reward

3. Competition Entry Reward

4. Unique Coupon Reward

5. Non-Unique Coupon Reward

Use Cases

1. Campaign Integration

2. Manual Customer Service Grant

3. Progressive Rewards

Validation Rules

Points Reward

Product Reward

Competition Entry Reward

Unique Coupon Reward

Non-Unique Coupon Reward

Error Responses

400 Bad Request

400 Invalid Config

404 Not Found

409 Conflict

500 Internal Server Error

Best Practices

Related APIs

Support