1. MarketPlace
Game Loom
  • Game Loom
    • 👋 Welcome to Game Loom
  • Getting started
    • Introduction
    • 👤 Authentication
  • User Registration
    • Introduction
    • Get Countries
      GET
    • Get Cities
      GET
    • Single user registration
      POST
    • Bulk Register Users
      POST
  • Notifications
    • Overview
    • Receiving Event Notifications via Webhooks
    • Get All notifications for specific user
      GET
  • Rewards
    • Overview
    • Integrate with you reward system
    • Points
      • Record user point event
      • Get user points
      • Get Specific user point
    • Levels
      • Record user level event
      • Get user levels
      • Get Specific user level
    • Badges
      • Award badge to user
      • Get user badges
      • Get Specific user badge
  • Challenges (Gamification elements)
    • Introduction
    • Leaderboard
      • Get available leaderboards for user
      • Submit score to a leaderboard
      • Get user's leaderboard participation history
      • Get leaderboard details
      • Get leaderboard ranking
      • Get user's record for a leaderboard
      • Get user's entry history for a leaderboard
    • Survey
      • Overview
      • Get available surveys for user
      • Start a new survey participation
      • Get detailed user participation
      • Get user's survey participation history
      • Abandon survey participation
      • Save individual answer to survey question
      • Submit completed survey
      • Submit Survey with answers (One-Step Submission)
    • Quiz
      • Get available quizzes for user
      • Submit complete quiz answers
      • Get comprehensive user quiz history
      • Get comprehensive quiz attempt details
    • Open Challenge
      • Overview
      • Get available open challenges for user
      • Complete an open challenge
      • Get user's open challenge participation history
      • Get user open challenge by ID
    • Schemas
      • Survey Schame
  • MarketPlace
    • Overview
    • Marketplace
      • Browse available gifts for user
      • Get gift details
      • Redeem a gift
      • Get user's redemption history
    • Schemas
      • ProblemDetails
  1. MarketPlace

Overview

Marketplace#

Welcome to the GameLoom Marketplace — the reward redemption system where your users can browse and redeem gifts using their earned points.

How It Works#

1.
Browse gifts — Retrieve available gifts for a user. The system automatically filters based on stock, expiry, and user targeting
2.
View gift details — Get full information about a specific gift including pricing, stock, and redemption rules
3.
Redeem a gift — Deduct points from the user's balance and create a redemption record. Stock is managed automatically
4.
Track redemptions — View the user's redemption history including delivery status

Key Concepts#

Gifts#

Redeemable items available in the marketplace. Each gift has:
Price in points and/or SAR
Stock — limited or unlimited quantity
Expiry — optional expiration date
Ranking — display order in the marketplace

Categories#

Gifts are organized into categories (e.g. Electronics, Food & Drinks). A default "All" category exists for every company.

Point Types#

Each gift is linked to one or more point types from the Rewards service. When redeeming, the user must specify which point type to use. Only eligible point types are accepted.
Use the pointTypeIds array from the gift details to know which point types a gift accepts.

Targeting#

Gifts can be public (visible to all users) or private (targeted). Private gifts are only visible to users who match the targeting criteria:
CriteriaDescription
genderFemale or Male
minAge / maxAgeAge range
countryCountry (case-insensitive)
cityCity (case-insensitive)
segmentUser segment (e.g. Premium, Silver, VIP)
Public gifts are always visible. Private gifts are automatically filtered based on the user's profile from the Registration service.

Redemptions#

When a user redeems a gift:
Points are deducted from their balance via the Rewards service
Stock is decremented atomically (for limited-stock gifts)
A redemption record is created with a snapshot of the gift at the time of redemption
If the gift requires delivery, the redemption starts with deliveryStatus: Pending
If the gift has a redemptionValue (coupon code, voucher, link), it is returned in the response

Redemption Rules#

Gifts can have rules that affect the redemption flow:
RuleEffect
collectCustomerInfo: trueUser must provide customerName and customerPhone when redeeming
deliveryRequired: trueUser must provide deliveryName, deliveryPhone, deliveryCity, and deliveryAddress when redeeming
maxRedeemPerUser: NEach user can redeem this gift at most N times. null = unlimited

Error Format#

All errors follow the ProblemDetails format:
{
  "type": "GIFT_NOT_FOUND",
  "title": "Gift not found",
  "status": 404,
  "detail": "Gift not found",
  "correlationId": "0HNI1NSLEBIHO:00000001",
  "timestamp": "2026-03-22T16:00:00Z"
}
When Accept-Language: ar is set, the title and detail fields return Arabic messages.

Error Codes#

Error CodeStatusDescription
GIFT_NOT_FOUND404Gift not found, inactive, expired, or deleted
GIFT_NOT_AVAILABLE400Gift is not active or has expired
GIFT_OUT_OF_STOCK400No remaining stock
POINT_TYPE_NOT_ELIGIBLE400The submitted pointId is not accepted for this gift
MAX_REDEEM_LIMIT_REACHED400User has reached the maximum redemption limit
CUSTOMER_INFO_REQUIRED400customerName and customerPhone are required
DELIVERY_INFO_REQUIRED400Delivery details are required
INSUFFICIENT_POINTS400User does not have enough points
USER_NOT_FOUND_OR_INACTIVE400User does not exist or is inactive
GIFT_NOT_TARGETED_FOR_USER403Gift not available based on targeting criteria
SERVICE_UNAVAILABLE503A dependent service is temporarily unavailable

Endpoints#

MethodPathDescription
GET/api/v1/marketplace/user/{userKey}/giftsBrowse available gifts
GET/api/v1/marketplace/user/{userKey}/gifts/{id}Get gift details
POST/api/v1/marketplace/user/{userKey}/redeemRedeem a gift
GET/api/v1/marketplace/user/{userKey}/redemptionsGet user's redemption history
Modified at 2026-04-13 22:59:00
Previous
Survey Schame
Next
Browse available gifts for user
Built with