Get User Reward Stores and Reward Store Offers
Gets reward stores eligible for the customer (user). Then gets and displays for the customer whatever offers a specific reward store contains.
Sequence Diagram
See the overall flow for this task below.
API Endpoints & Constraints
POST /api/2.0/offers/rewardstores/get_user_reward_stores
POST /api/2.0/offers/rewardstores/get_reward_store_offers
The get_user_reward_stores
endpoint cited above can return the customer, or user's, point balance when the include_point_balances
parameter is set to "true."
The get_reward_store_offers
endpoint cited above can locate the appropriate offers by passing a reward_store_ids array. Furthermore, the endpoint may specify the following:
-
Whether to include or exclude expired offers.
-
Whether to include or exclude free (zero points) offers.
-
Whether to limit returned offers to only those that are obtainable by the customer (user).
-
Whether to apply additional filters that limit offers per reward store by a minimum or maximum price range.
-
Note too that valid sort column parameter values include internal_name,
start_date
, andend_date
. If nothing is passed, the default sort parameter applied isstart_date
.
Bear in mind the following limits pertaining to the get_reward_store_offers
endpoint cited above:
-
Maximum number of reward store IDs is 100.
-
Maximum number of rows returned is 1,000. So, the Take parameter must be 1,000 or less. Note that page size is an influencing factor on performance, both latency and throughput (TPS).
-
Skip parameter value must be limited/provided as a 32-bit signed integer.
Alternative Path
Instead of a two-step flow to obtain reward stores offers, you can omit "Get user eligible reward stores" and call only "Get reward store offers, using reward store ID." Just be sure to specify the reward store you want in the reward_store_ids
array. Doing so effectively hard codes the reward store ID in the request for the offers. This approach is used primarily when only one reward store exists in a client's implementation and every customer will access the same store. It is an excellent way of reducing API calls; only one call is necessary to get the reward store offer, rather than first looking for the customer's reward store eligibility and then getting the reward store offers.
Best Practices
As you build applications or web sites that implement SessionM APIs, bear in mind these best practices:
- Maintain a limited number of offers per any reward store, and limit the number of reward stores in use because large numbers of reward stores - containing large numbers of offers - create latency issues for both mobile and e-commerce application user experiences.
- Consider a few recommendations pertaining to reward store eligibility:
- When eligibility requirements govern access to loyalty reward stores, it's recommended that the reward stores eligible for the customer (user) are requested first. These reward stores are "public" or part of loyalty tiers or invitations proffered to the customer. Additionally, these reward stores are currently live or available (based on start and end dates).
- When no eligibility requirements apply but multiple reward stores are in use for the loyalty program (or it is inadequate to configure the reward store ID), use the
get_reward_stores
endpoint to search for reward stores. - When no eligibility requirements apply at all, it is recommended that a value for the reward store be set in the
reward_store_ids
array available as a parameter when fetching reward store offers. - Also note that reward store eligibilities can be retrieved using the
get_reward_store_eligibilities
endpoint. The eligibility information returned in its response can be used to query for a customer's (or user's) eligible reward stores.