Integrate the Marketplace into Your App

Let your users browse and redeem gifts using their earned points — directly from your application.

GameLoom handles everything: stock management, point deduction, eligibility filtering, delivery tracking, and localization. You just need to call the API and display the results.

Integration Flow

Here's the typical flow for integrating the marketplace into your app:

1. Show Available Gifts

Call the browse endpoint to get gifts your user can see:

GET /api/v1/marketplace/user/{userKey}/gifts

Query parameters:

pageNumber (default: 1)

pageSize (default: 10, max: 100)

categoryId — filter by category (optional)

language — language code such as en or ar (optional). When set, name and imageUrl are resolved to that language. Falls back to the default value when no translation exists.

We automatically filter out gifts that are:

Out of stock or expired

Inactive or deleted

Targeted to a different user segment (based on their profile)

You'll get back a list of gifts with name, image, price (in points and/or SAR), stock info, and display settings.

2. Show Gift Details

When the user taps on a gift, fetch the full details:

GET /api/v1/marketplace/user/{userKey}/gifts/{id}?language=ar

The response includes everything you need to build your detail page:

Price and stock information

Redemption message and redemption value (resolved to the requested language)

Whether customer info or delivery address is required

Important: Check these two flags before showing the redeem button:

collectCustomerInfo — if true, you'll need to collect the user's name and phone number

deliveryRequired — if true, you'll need to collect delivery name, phone, city, and address

If either flag is true, show the appropriate form fields before allowing redemption.

3. Redeem a Gift

When the user confirms, call the redeem endpoint:

POST /api/v1/marketplace/user/{userKey}/redeem?language=ar

Each gift has a single linked point type. The system uses that point type automatically — no need to pass pointId.

Minimal request (no customer info or delivery needed):

{
  "giftId": "{{gift-id}}"
}

With customer info (when collectCustomerInfo: true):

{
  "giftId": "{{gift-id}}",
  "customerName": "Ahmed",
  "customerPhone": "+966501234567"
}

With delivery (when deliveryRequired: true):

{
  "giftId": "{{gift-id}}",
  "customerName": "Ahmed",
  "customerPhone": "+966501234567",
  "deliveryName": "Ahmed",
  "deliveryPhone": "+966501234567",
  "deliveryCity": "Riyadh",
  "deliveryAddress": "King Fahd Road, Building 42"
}

What happens on our side:

We verify the user exists and is active

We check the gift is available, in stock, and the user is eligible

We check any per-user redemption limits

We deduct points from the user's balance automatically

We create a redemption record and return it to you

What you get back:

redemptionMessage — a success message to show the user (resolved to the requested language if localized)

redemptionValue — if the merchant set a coupon code, voucher, or link, it's here. Show it to the user.

deliveryStatus — "Pending" if the gift requires delivery, null if it doesn't

Full snapshot of the gift at the time of redemption (name, image, points spent)

4. Show Redemption History

Let users view their past redemptions:

GET /api/v1/marketplace/user/{userKey}/redemptions

Each redemption includes the gift name, points spent, order status, and delivery status. Use this to build a "My Rewards" or "Order History" page.

Localization

All user-facing endpoints accept an optional language query parameter (e.g. ?language=ar).

When a gift has localized content, the top-level fields (name, description, imageUrl, redemptionMessage) are resolved to the requested language. If no translation exists for that language, the default value is returned.

User endpoints return only the resolved strings — no raw localization map is exposed to end users.

What You Need to Handle

Before Redeeming

Check the gift's requirements from the detail endpoint:

Flag	What to do
`collectCustomerInfo: true`	Show name + phone fields in your redeem form
`deliveryRequired: true`	Show delivery address fields in your redeem form
Neither is true	Just show a confirm button — no extra fields needed

Error Responses

All errors return a standard format with an error code:

{
  "type": "GIFT_OUT_OF_STOCK",
  "title": "Gift is out of stock",
  "status": 400,
  "detail": "Gift is out of stock"
}

Set Accept-Language: ar to get Arabic error messages.

Error codes you should handle:

Error Code	When it happens	Suggested UX
`GIFT_NOT_FOUND`	Gift doesn't exist or was removed	Remove from your list, show "no longer available"
`GIFT_NOT_AVAILABLE`	Gift is inactive or expired	Disable the redeem button, show "not available"
`GIFT_OUT_OF_STOCK`	Stock ran out	Disable the redeem button, show "out of stock"
`INSUFFICIENT_POINTS`	User doesn't have enough points	Show current balance and required points
`MAX_REDEEM_LIMIT_REACHED`	User already redeemed the max times	Hide redeem button, show "already redeemed"
`CUSTOMER_INFO_REQUIRED`	Missing name/phone	Show the customer info form
`DELIVERY_INFO_REQUIRED`	Missing delivery address	Show the delivery form
`GIFT_NOT_TARGETED_FOR_USER`	User isn't eligible for this targeted gift	Don't show the gift (this shouldn't happen if you use the browse endpoint, which filters automatically)
`USER_NOT_FOUND_OR_INACTIVE`	User does not exist or is inactive	Show an error, verify user registration

API Reference

Method	Path	Description
GET	`/api/v1/marketplace/user/{userKey}/gifts`	Browse available gifts
GET	`/api/v1/marketplace/user/{userKey}/gifts/{id}`	Get gift details
POST	`/api/v1/marketplace/user/{userKey}/redeem`	Redeem a gift
GET	`/api/v1/marketplace/user/{userKey}/redemptions`	Get redemption history

For full request/response schemas, see the individual endpoint pages.

Overview

Integrate the Marketplace into Your App#

Integration Flow#

1. Show Available Gifts#

2. Show Gift Details#

3. Redeem a Gift#

4. Show Redemption History#

Localization#

What You Need to Handle#

Before Redeeming#

Error Responses#

API Reference#