​
Overview

The Thanx APIs now support points for a variety of integration use-cases. This document is intended to provide developers of both consumer UX integrations (via the Thanx Consumer APIs) and ordering integrations (via the Thanx Loyalty APIs) an in-depth guide covering what is required to support points. Please review this integration guide for an overview of what the expected changes are when updating your integration to support points. For specific API references, you can refer to the various API endpoints linked in this document. For any additional support, please reach out to us at developer.support@thanx.com. Our team can help answer any specific technical questions and can prepare a sandbox environment configured for points for your team to test updated integrations against before promoting the changes to production. There are multiple audiences for this integration guide and each section may not be applicable for each integration partner. While reading the whole document may be helpful for a full understanding of the various integration mechanisms, here is some guidance:
  • Entities - all developers should review this section
  • Consumer UX integration - developers that only manage consumer UX experiences that are integrated with the Thanx Consumer APIs should review this section
  • Order provider integration - developers that manage ordering provider systems that are integrated with the Thanx Loyalty APIs for redemption should review this section
  • Consumer UX & ordering integration - developers that manages systems that integrate with both the Thanx Consumer APIs (consumer UX integration) and the Thanx Loyalty APIs (ordering loyalty integration) should review this section and both of the above sections.

​
Entities

As part of this new functionality, there are now two additional conceptual entities that have been added to the Thanx platform that are available to be interacted with via API.

​
Points Experience

Points experiences are configuration that defines the currency that a user can earn points torward, including the conversion rate, imagery, and basic copy. Users can earn points for each configured experience through various interactions with the platform - making purchases, being issued bonus points through a campaign, etc.

​
Points Product

For each points experience, a merchant can configure many different points products via the merchant dashboard, which can be enabled/disabled/updated in realtime. Points products are configure that describe the reward a user can receive in exchange for accrued points for a given points experience. Each product can be redeemed for a configurable amount of points. Upon exchange of a user’s points balance for a points product, the configured amount of points are deducated from the user’s points balance and a reward will be added to the user’s account. These rewards can then be interacted with as any other reward would.

​
Consumer UX integration

​
Fetch points experiences

The configured points experiences for a merchant are queryable via the GET /points_experiences endpoint. The information in this endpoint can be used to communicate what a user is earning points torward.

​
Fetch points balance

The points balance that a user currently holds for a given points experience can be queried via the GET /points_experiences/:id/balance endpoint.

​
Fetch points products

The available points products a user can exchange points for are queryable in the GET /points_products endpoint. These can optionally be filtered by points experiences via the points_experience_id query parameter.

​
Points redemption

When a user accrues enough points and would like to exchange points for a points product, there are different mechanisms for redemption depending on the venue of redemption. Regardless of the redemption mechanism, however, the process is conceptually the same:
  • Points exchange is initiatied
  • User’s points balance is validated to ensure the user’s balance can cover the points cost of the product
  • User’s points balance is deducted by the cost of the points product
  • A reward is issued to that user, matching the configuration of the points product
  • The reward can then be used as would any other reward issued to the user via campaigns or other mechanisms

​
Non-ordering points redemption

For non-ordering redemption, this exchange can be initiatied via the POST /points_products/:id/rewards endpoint.

​
Ordering points redemption

This redemption mechanism is available to all non-Olo ordering providers that have integrated with the Thanx Loyalty APIs.
  • Exchange a user’s points balance for a reward following the standard non-ordering redemption flow described above.
  • That reward ID can then be applied to the basket directly using the existing ordering provider APIs.
  • Once the order is finalized, that reward will be automatically finalized and unavailable for future redemption.
This redemption mechanism works even if the integrated ordering partner has not explicitly updated their integration to support points. If the ordering partner you have integrated with has updated their integration to support points directly, there may be simpler mechanisms for points redemption (eg. functionality to apply a points product directly to a basket for redemption). Please discuss your options with your ordering provider.

​
Olo ordering redemption

Thanx is deeply integrated with the Olo platform and this integration offers a few different mechanisms for redemption. For developers integrating with both the Thanx APIs and directly with the Olo Ordering APIs for order placement, there are two mechanisms for redemption available: Automatic exchange
  • The Thanx integration with the Olo API automatically includes the points products that a user has enough points to redeem for in the Olo loyalty rewards API endpoint, in addition to any already delivered rewards (GET /baskets/{uid}/loyaltyrewards/qualifying)
    • Note that the Olo API does not natively support points, so information about how many points will be deducted from the user’s balance or additional information about the points product will not be exposed by the Olo API.
  • The UIDs of the available points products that are returned by the Olo API will match the olo_uid in the GET /points_products endpoint.
  • The points product olo_uid can be used just as any other Reward ID would be used in the Olo API.
  • Upon placement of the order, the points exchange process described above will be transparently handled in the background - deducting the user’s balance, creating a new reward, and applying that reward to the Olo basket.
Manual exchange This flow allows for full control of the redemption process and the ability to communicate more details about the points product to the user.
  • Exchange a user’s points balance for a reward following the standard non-ordering redemption flow described above.
  • Once the reward is issued, Olo will then return that reward in the Olo API (GET /baskets/{uid}/loyaltyrewards/qualifying)
  • This reward will also be available in the GET /rewards endpoint and the olo_uid attribute will match the reward IDs returned by the Olo API.
  • That reward ID can be applied to the basket via Olo APIs.
  • Once the order is finalized, that reward will be automatically finalized and unavailable for future redemption. points.

​
Ordering provider integration

For ordering providers that have integrated with the Thanx Loyalty APIs, the Thanx APIs have been updated to minimize the number of endpoints that partners are required to interact with. While the endpoints available above are available to ordering partners, our team has attempted to make the integration upgrade process as simple as possible. The only two endpoints required for integration are: Additional data attributes have been included in these endpoints. Note that the functionality of all existing integrations with these endpoints will still be fully functional. These changes are only required to support the new points loyalty engine.

​
Account endpoint changes

  • The progress attribute will no longer be used for merchants that have fully transitioned to points
  • The points attribute has been added, which is an array of all the points experiences of the given merchant and the user’s current points balance of that points experience’s currency.
  • The points_products attribute has been added, which is an array of all the available points products that is available for the given merchant.
    • Note that this returns all of the merchant’s points products, regardless of if the user can currently afford the points product. This enables ordering providers to optionally display which points products users can continue to earn toward.
    • Only points products available for online redemption will be included
    • The schema of the points products largely matches the schema of rewards, except for a few items:
      • points_experience_id is present, which is the ID of the points experience queryable via the GET /points_experiences/:id endpoint
        • These points experience IDs match the data available in the points attribute.
      • points is present, which is the number of points required to exchange this points product for a reward
      • retire_at is not relevant for points products, as points have not yet been exchanged for reward
    • The state of the points products will be redeemable if the user has enough points balance to cover the cost of the points product and unredeemable if the user does not have enough points.

​
Basket endpoint changes

In addition to the rewards attribute, requests now accept a points_products attribute which can include a points product ID. If a points product ID is specified for a basket, the points product exchange will be automatically triggered on receipt of the placed event. The reward that was created as a result of the points product exchange will be marked as used when the billed event is received (using the same points product ID used in that basket’s placed event. Note that only a single reward or points product can currently be applied to a basket. The request will 400 if multiple rewards or points products are specified in the request. Detailed descriptions of what happens to points products when requests for each basket state are received is documented in POST /baskets.

​
Consumer UX & ordering integration

For developers that manage both consumer UX and ordering systems that are integrated with the Thanx APIs, the above guidance still applies, though there is some additional flexibility. For points product redemption for digital orders, developers can choose to exclusively leverage the explicit API for exchanging points products and leave existing Loyalty API interactions untouched, ignoring the additional data attributes included in the GET /account endpoint. This is an option since exchanging points for a points products issues a reward to a user’s account which will then be available to be passed to the baskets endpoint via the rewards attribute. Developers can also choose to manage these workflows separately and handle non-ordering points redemption via the explicit API for exchanging points products and handle ordering points redemption via the information coming from the account and basket endpoints. This decision is up to the developer to decide what is easiest for the given integration. Our developer support team is available to provide advice and support for your specific use-case.

​
Integration support

After reading this guide, when you are ready to update your existing integration, feel free to reach out to developer.support@thanx.com. Our developer support team can provide any integration support that you need, including access to a sandbox environment configured with the new points configuration described in this document. Don’t hesitate to reach out!