Redeem a gift

Redeems a gift for the user by deducting points from their balance.

Validation Flow

The system performs the following checks in order before processing the redemption:

User validation — Verifies the user exists and is active via the Registration service

Gift validation — Gift must be Active, not expired, and not deleted

Point type check — The submitted pointId must be one of the gift's eligible point types

Redeem limit check — If maxRedeemPerUser is configured, checks the user has not exceeded the limit

Targeting check — If the gift is private (targeted), the user must match the targeting criteria

Stock check — Atomically decrements stock. Returns 400 if out of stock

Point deduction — Deducts points via the Rewards service. If insufficient balance, stock is rolled back automatically

Record creation — Creates the redemption record with snapshot data (gift name, image, price at time of redemption)

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.

Point Type

The pointId field is optional. If omitted, the system automatically uses the first eligible point type linked to the gift. If the gift accepts multiple point types and the user wants to choose a specific one, they can provide pointId explicitly.

curl --location -g --request POST '/api/v1/marketplace/user/{{user-key}}/redeem' \ --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" }'

{ "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": "68e3ee00d81b74c5fe9ac28c", "redemptionValue": null, "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, "redemptionMessage": "Enjoy your new headphones!" }

Redeem a gift

Redeem a Gift

Validation Flow

Conditional Fields

Point Type

Request

Responses

Redeem a gift

Redeem a Gift#

Validation Flow#

Conditional Fields#

Point Type#

Request

Responses

Redeem a Gift

Validation Flow

Conditional Fields

Point Type