This API is used to get the rewards purchased by the user, without any aggregation on reward ID, and gives a unified view of the rewards purchased in order of the last purchased date.

Example Consider the below scenario:

A customer has 10 vouchers from the same reward
3 vouchers each from 4 different rewards
Page size= 5

The API retrieves the details of the last 5 vouchers issued to the customer.

If you use the Get rewards for user API, the API retrieves the information on the total rewards received by the customer (22 rewards).

Let’s say below is the structure of the table and for the same customer, we have issued 10 coupons but they belong to 3 rewards

With the new response if pagination is 5, then only below 5 records will be returned

👍
Note

For detailed information about our APIs and for hands-on testing, refer documentation in API overview and step-by-step guide on making your first API call in Make your first API call .

For the list of items in query param list, rewards will be returned if expected value found. Meaning if vendor param has 3 values passed but rewards only exist for 2 of the three vendors. The rewards for the 2 vendors will be returned .

When Dual Eligibility feature enabled, a reward can be issued to multiple users registered with the same secondary identifiers, as long as they have unique primary identifiers.

The "Get all reward transactions for a user" API lists all reward issuance attempts, including failures, while the "Get Purchased Rewards for user" API shows only the rewards successfully received by the user.

Prerequisites

Authentication: Basic or OAuth authentication
Default access group

Resource information


URL	/api_gateway/rewards/core/v1/user/userReward/brand/`{BrandName}`
Pagination	Yes
Batch support	No
Rate limit information	None

API endpoint example

https://eu.api.capillarytech.com/api_gateway/rewards/core/v1/user/userReward/brand/{BrandName}

Request path parameters

Parameters	Data Type	Description
BrandName*	String	Name of the brand. Ex: BUKL

Request query parameters

Fields	Type	Description
mobile/email/externalId*	String	The mobile number, email, or external ID of the customer for whom to fetch rewards. Example: 9988776654
username*	String	The Till ID used in the authorization of the request. Example: swati
language	String	Filters the response based on the reward language. Use this parameter to retrieve rewards in a specific language. For example, to display rewards in English, set the parameter to en.
orderBy	String	Specify asc to order the results in ascending order of sortBy value, or desc to order in descending order.
sortBy	String	Sort the results by a specific parameter. Supported values: INTOUCH_VOUCHER, INTOUCH_VOUCHER_EXPIRY, PURCHASE_DATE. Default: PURCHASE_DATE
page	Integer	Retrieves details of a specific page. Pass 0 to disable pagination. For example, page=2&size=10 shows 10 results on page 2.
size	Integer	The number of results to show per page. Default: 100
category	String	Filters rewards based on reward category IDs. Multiple category IDs can be passed in the query parameter, with no limit on the number of category IDs that can be provided.
groupName	String	Filters details based on group names. Multiple group names can be passed in the query parameter, with no limit on the number of group names that can be provided.
vendorId	Integer	Filters rewards by vendor IDs. Multiple vendor IDs can be passed in the query parameter, with no limit on the number of vendor IDs that can be provided.
typeOfReward	String	Filters rewards based on specific types. Supported values are INTOUCH_REWARD, VENDOR_INTOUCH_REWARD, VENDOR_ONLY_REWARD, CART_PROMOTION, SWEEPSTAKES, and GAMES. Multiple typeOfReward values can be passed, and the filter is case-sensitive.
fromPurchaseDate	Long	Filters rewards by purchase date in epoch format. This filter works only if both fromPurchaseDate and toPurchaseDate are provided.
toPurchaseDate	Long	Filters rewards by purchase date in epoch format. This filter works only if both fromPurchaseDate and toPurchaseDate are provided.
rewardId	Long	Use this parameter to filter and return specific reward details.
couponCodeCase	String	This parameter helps retrieve the coupon code in the desired letter cases. By default, the system automatically converts the coupon code to uppercase. Supported values are: LOWER, UPPER, and AS_IT_IS. <br> <br> LOWER: Converts the coupon code to lowercase. Example: "ABCD1234" → "abcd1234" <br>- UPPER: Converts the coupon code to uppercase. Example: "abcd1234" → "ABCD1234" <br>- AS_IT_IS: Returns the coupon code exactly as it was created. Example: "abAB123" → "abAB123"
fromEventDate	Long	Filters purchased rewards starting from a specified event date. For example, this allows you to filter all rewards earned by a customer between May 1st and 22nd based on the exact event date.Must be used along with the toEventDate query parameter. Time format is Unix timestamp.
toEventDate	Long	Filters purchased rewards up to a specified event date. Must be used along with the fromEventDate query parameter. Time format is Unix timestamp.
fromExpiryDate	Long	Filters purchased rewards starting from a specified expiry date in epoch time format.For example, this allows you to filter all rewards earned by the customer expiring between October 25th and 31st, based on their exact expiry date. Must be used along with the `toExpiryDate` query parameter.
toExpiryDate	Long	Filters purchased rewards up to a specified expiry date in epoch time format. Must be used along with the `fromExpiryDate` query parameter.

https://eu.api.capillarytech.com/api_gateway/rewards/core/v1/user/reward/brand/BUKL

Response Parameters

Field	Type	Description
status	Object	Defines the container for information about the success or failure of the API call.
. success	Boolean	Indicates whether the operation was successful.
. code	Integer	Defines a numeric code representing the result of the operation.
. message	String	Defines a descriptive message providing additional context about the operation's outcome.
rewards	Array	Defines an array of objects, where each object contains details about a reward issued to the user.
. typeOfReward	String	Specifies the type of reward.
. pointsRedeemed	Integer	Indicates the number of points redeemed by the user for this reward.
. rewardId	Long	Defines a unique identifier for the reward.This field will return NULL if the voucher or coupon was issued via a campaign.
. transactionId	Long	Defines the unique identifier for the transaction associated with this reward.
. issueRewardRefId	String	Defines a reference ID for the reward issuance, used for tracking.
. rewardIssueDate	Long	Specifies the date and time when the reward was issued, represented as a UNIX timestamp in milliseconds.
. rewardIssueDateTime	String	Specifies the date and time when the reward was issued, in ISO 8601 format
. userRewardExpiry	String	Specifies the expiration date and time for the user's reward, in ISO 8601 format.
. userRewardExpiryDateTime	String	Specifies the expiration date and time for the user's reward, in ISO 8601 format.
. userRewardDetails	Object	Defines the container for additional details about the reward, including metadata and configurations.
.. id	Long	Defines a unique identifier for the reward details.
.. name	String	Specifies the name of the reward as displayed in the system.
.. description	String	Defines a brief text describing the reward and its features or purpose.
.. imageId	String	Defines an identifier for the primary image associated with the reward.
.. imageUrl	String	Defines a URL linking to the full-sized image of the reward.
.. thumbnailId	String	Defines an identifier for the thumbnail image of the reward.
.. thumbnailUrl	String	Defines a URL linking to the thumbnail-sized image of the reward.
.. termAndConditionsId	String	Defines an identifier for the terms and conditions document associated with the reward.
.. termAndConditionsUrl	String	Defines a URL linking to the terms and conditions document for the reward.
.. tier	String	Specifies the tier to which the reward belongs, often used in loyalty programs.
.. label	String	Defines a tag or label associated with the reward for categorization or filtering.
.. priority	Integer	Specifies the priority level of the reward.
.. intouchPoints	Integer	Specifies the number of loyalty points required to redeem this reward.
.. group	String	Specifies the group or category associated with the reward.
.. startTime	String	Specifies the date and time when the reward becomes available in ISO 8601 format.
.. startDateTime	String	Specifies the start date and time of the reward's availability in ISO 8601 format.
.. endTime	String	Specifies the date and time when the reward’s availability in ISO 8601 format.
.. endDateTime	String	Specifies the end date and time of the reward.
.. expired	Boolean	Indicates whether the reward has expired.
.. started	Boolean	Indicates whether the reward is currently active and can be redeemed.
.. programId	Long	Defines a unique identifier for the program under which the reward is issued.
.. vendorId	Long	Defines a unique identifier for the vendor associated with the reward.
.. categoryList	Array	Defines a list of categories to which the reward belongs, often used for filtering or classification.
... id	Integer	Defines the unique identifier for a specific category associated with the reward.
... name	String	Specifies the name of the category (e.g., "joreward").
... enabled	Boolean	Indicates whether the category is currently active and usable.
... createdOn	Long	Specifies the timestamp indicating when the category was created.
... lastUpdatedOn	Long	Specifies the timestamp indicating when the category was last updated.
... createdBy	String	Defines the identifier for the user who created the category.
... lastUpdatedBy	String	Defines the identifier for the user who last updated the category.
... createdOnDateTime	String	Specifies the category creation date in ISO 8601 format.
... lastUpdatedOnDateTime	String	Specifies the category's last update date in ISO 8601 format.
.. loyaltyProgramCriteria	Object	Defines the criteria for loyalty programs related to the reward.
.. groups	Array	Defines a list of any specific groups associated with the reward, used for segmentation purposes.
.. rewardRank	Integer	Specifies the rank or position of the reward within its category or list.
.. images	Array	Defines a list of any additional images associated with the reward.
.. videos	Array	Defines a list of any videos related to the reward.
. revenueDetails	Object	Defines a container for revenue-related information for the reward.
. paymentDetails	Object	Defines a container for details about the payment configuration for the reward.
. redemptionDetails	Object	Defines a container for details about how the reward can be redeemed, such as type and value.
.. redemptionType	String	Specifies the type of redemption.
.. redemptionValue	Integer	Specifies the value associated with the redemption.
. transactionCustomFields	Object	Defines a container for custom fields defined for the transaction.
. fulfillmentDetails	Object	Defines a container for fulfillment-specific information for the reward.
. issueDateTime	String	Specifies the date and time when the reward was awarded to the customer.
. eventDateTime	String	Specifies the date and time when a triggering event occurred, initiating the reward earning.
. code	String	Defines a unique code associated with the reward, often used for tracking or redemption.
. vendor	String	Defines the vendor associated with the reward.
. seriesId	String	Defines an identifier for the series or batch of the reward.
intouchUserId	String	Defines the unique identifier of the user in the system.
pagingDto	Object	Defines a container for details about the pagination of the results, such as total elements and pages.
. last	Boolean	Indicates whether this is the last page of results.
. totalElements	Integer	Indicates the total number of rewards returned by the query.
. totalPages	Integer	Indicates the total number of pages available for the query results.
. numberOfElements	Integer	Indicates the number of elements on the current page.
. first	Boolean	Indicates whether this is the first page of results.
. size	Integer	Specifies the number of elements per page, as requested in the query.
. number	Integer	Indicates the current page number in the results.

Error codes

Error Code	Description
15006	The request is missing the primary identifier.
1014	The provided identifier does not match any existing customer.
404	The specified customer was not found in the organization.