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.

CUSTOMER CUSTOMER CLIENT MIDDLEWARE CLIENT MIDDLEWARE SESSIONM SESSIONM GET REWARD STORE OFFERS Navigate to reward store page and start order Get user eligible reward stores Return reward stores, including eligible reward store IDs for customer Get reward store offers, using reward store ID Return reward store offers associated with reward store ID Display reward store offers on reward store page

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, and end_date. If nothing is passed, the default sort parameter applied is start_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.