Browse available gifts for user

GET

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

Browse Available Gifts

Retrieves all gifts currently available for the user to redeem, with optional filtering by category.

This endpoint automatically filters out gifts that are not relevant to the user:

Inactive or cancelled gifts are excluded

Expired gifts (expiresAt in the past) are excluded

Out of stock gifts are excluded

Targeted gifts are only shown if the user matches the targeting criteria (gender, age, country, city, segment)

Public gifts are always visible to all users. Private (targeted) gifts are only shown when the user's profile — fetched from the Registration service — matches the gift's targeting rules.

Pagination

Results are paginated. Use pageNumber and pageSize to control the page. Results are sorted by ranking (ascending), then by creation date (descending).

Request

Path Params

Query Params

Header Params

Responses

🟢200Success

application/json

Body

Request Example

Shell

JavaScript

Java

Swift

curl --location -g --request GET '/api/v1/marketplace/user/{{user-key}}/gifts?pageNumber=1&pageSize=10&categoryId' \
--header 'x-api-key: {{api-key}}'

Response Example

{
    "items": [
        {
            "id": "b1c2d3e4-5678-9abc-def0-111111111111",
            "name": "Premium Headphones",
            "imageUrl": "https://example.com/headphones.png",
            "categoryName": "Electronics",
            "status": "Active",
            "pricePoints": 500,
            "priceSar": 50,
            "isUnlimited": false,
            "quantity": 10,
            "remainingStock": 7,
            "ranking": 1,
            "redemptionCount": 3,
            "createdAt": "2026-03-20T09:00:00Z"
        },
        {
            "id": "b1c2d3e4-5678-9abc-def0-222222222222",
            "name": "Coffee Voucher",
            "imageUrl": null,
            "categoryName": "Food & Drinks",
            "status": "Active",
            "pricePoints": 100,
            "priceSar": null,
            "isUnlimited": true,
            "quantity": null,
            "remainingStock": null,
            "ranking": 2,
            "redemptionCount": 18,
            "createdAt": "2026-03-18T12:00:00Z"
        }
    ],
    "pagination": {
        "currentPage": 1,
        "pageSize": 10,
        "totalCount": 2,
        "totalPages": 1,
        "hasPrevious": false,
        "hasNext": false
    }
}

Modified at 2026-04-13 23:17:31

Overview

Get gift details

Browse available gifts for user