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
      • Get gift details
        GET
      • Redeem a gift
        POST
      • Get user's redemption history
        GET
    • Schemas
      • ProblemDetails
      • Pagination
  1. Marketplace

Redeem a gift

POST
/api/v1/marketplace/user/{userKey}/redeem

Redeem a Gift#

Redeems a gift for the user by deducting points from their balance. Each gift has a single linked point type — the system uses it automatically.

Validation Flow#

The system performs the following checks in order before processing the redemption:
1.
User validation — Verifies the user exists and is active via the Registration service
2.
Gift validation — Gift must be Active, not expired, and not deleted
3.
Targeting check — If the gift is private (targeted), the user must match the targeting criteria
4.
Redeem limit check — If maxRedeemPerUser is configured, checks the user has not exceeded the limit
5.
Customer info check — If required by the gift, validates name and phone are provided
6.
Delivery info check — If required by the gift, validates delivery details are provided
7.
Stock check — Atomically decrements stock. Returns 400 if out of stock
8.
Point deduction — Deducts points via the Rewards service. If insufficient balance, stock is rolled back automatically
9.
Record creation — Creates the redemption record with snapshot data (gift name, image, price at time of redemption)

Localization#

Pass ?language=ar to get the redemptionMessage resolved to that language.

Conditional Fields#

Some fields are conditionally required based on the gift's configuration:
If collectCustomerInfo is true on the gift → customerName and customerPhone are required
If deliveryRequired is true on the gift → deliveryName, deliveryPhone, deliveryCity, and deliveryAddress are required
You can check these flags by calling the Get gift details endpoint before redeeming.

Request

Path Params

Query Params

Header Params

Body Params application/json

Examples

Responses

🟢201Success
application/json
Gift redeemed successfully
Body

🟠400
🟠403
Request Request Example
Shell
JavaScript
Java
Swift
curl --location -g --request POST 'https://api-stg.98s.studio//api/v1/marketplace/user/{{user-key}}/redeem?language=ar' \
--header 'x-api-key: {{api-key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "giftId": "{{gift-id}}",
    "customerName": "Ahmed Mohammed",
    "customerPhone": "+966500000001",
    "deliveryName": "Ahmed Mohammed",
    "deliveryPhone": "+966500000001",
    "deliveryCity": "Riyadh",
    "deliveryAddress": "123 Main Street, Al Olaya District"
}'
Response Response Example
201 - Success
{
    "id": "c1d2e3f4-5678-9abc-def0-111111111111",
    "giftId": "b1c2d3e4-5678-9abc-def0-111111111111",
    "userId": "user-001",
    "giftName": "Premium Headphones",
    "giftImageUrl": "https://example.com/headphones.png",
    "pointsSpent": 500,
    "sarValue": 50,
    "pointId": "69962b0d0766fd3fe3c20116",
    "redemptionValue": null,
    "redemptionMessage": "استمتع بسماعاتك الجديدة!",
    "orderStatus": "Completed",
    "deliveryStatus": "Pending",
    "customerName": "Ahmed Mohammed",
    "customerPhone": "+966500000001",
    "deliveryName": "Ahmed Mohammed",
    "deliveryPhone": "+966500000001",
    "deliveryCity": "Riyadh",
    "deliveryAddress": "123 Main Street, Al Olaya District",
    "createdAt": "2026-03-22T16:00:00Z",
    "completedAt": "2026-03-22T16:00:01Z",
    "cancelledAt": null
}
Modified at 2026-04-17 18:37:25
Previous
Get gift details
Next
Get user's redemption history
Built with