--- title: "Configuring loyalty rewards on Associate App" slug: "configuring-loyalty-rewards-on-associate-app-1" tags: ["config api", "Associate App configuration", "Associate App", "loyalty rewards", "endless aisle", "order", "tutorial", "api", "external app"] updated: 2025-11-18T08:38:53Z published: 2025-11-18T08:38:53Z canonical: "docs.newstore.com/configuring-loyalty-rewards-on-associate-app-1" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.newstore.com/llms.txt > Use this file to discover all available pages before exploring further. # Configuring loyalty rewards on Associate App If your business uses a retail loyalty rewards program, you can use Associate App to offer customers with loyalty reward options. For example, you can offer discounts on products for customers who have been loyal to your brand for more than 1 year. > [!NOTE] > Important > > Currently, NewStore only allows Associate App to retrieve a list of coupons that have been configured in an external application, via a link in Associate App. To understand how integrating an external application with NewStore Associate App works, see [Integrating an external app with Associate App to retrieve data](/v1/docs/integrating-an-external-app-with-associate-app-to-retrieve-data#config-aa-external-app). To see how loyalty rewards can be used in the app, see [Adding loyalty reward coupons for a customer](/v1/docs/using-newstore-associate-app#add-rewards). ## Integrating Associate App with your loyalty system To configure Associate App to retrieve loyalty rewards data from your loyalty system: 1. Add your deeplink URL to the Associate App configuration. See [Enabling Associate App to offer loyalty rewards](/v1/docs/configuring-loyalty-rewards-on-associate-app#enabling-associate-app-to-offer-loyalty-rewards). 2. Associate App opens either the external app with a deeplink, or a webview with your web application, depending on the configuration in the next steps (`is_deeplink`): 1. The deeplink URL for your integration contains 4 query parameters: `token`, `externalIdentity`, `cart` and `store`: - The `token` parameter contains a `32-bit` security token. This token must be included in the query parameters when your integrated application performs a callback to Associate App. - The `externalIdentity` property allows a third-party entity to exchange an identity token issued by NewStore and use it to integrate their native apps with Associate App, without requiring the user to log into the third-party app or website. For more information, see [Sending an identity token to a third-party to integrate with Associate App](/v1/docs/configuring-loyalty-rewards-on-associate-app#sending-an-identity-token-to-a-third-party-to-integrate-with-associate-app). - The `cart` parameter is a string-encoded JSON blob containing the following data sent to the external application: | Data sent | Purpose for the external loyalty system | | --- | --- | | Customer email address | To identify if loyalty rewards apply to the customer | | Cart ID | To identify the cart | | Total remaining amount of the cart | To verify if a loyalty reward coupon is valid or not. For example, if the total remaining amount to be paid for an order is `USD 30`, a loyalty reward coupon worth `USD 100` cannot be applied. | | Currency | To identify which loyalty reward coupons will be applicable for the order. | | Selected coupons | Manually applied discount coupons that have already been applied to the cart in Associate App are sent in the form of an array. The external rewards system identifies and includes these coupons in the list of coupons sent back to the app, so the associate can remove them if needed. The order of the sent array determines the order in which the associate applied the coupons in Associate App. | | Items array | List of items added to the cart, sent to the external loyalty rewards system in the form of an array, which includes the following objects: - Item ID - Item Price - Product ID | | Grand total | The total amount of the cart including taxes. | | subtotal | The total amount of the cart before taxes. | - The `store` parameter is a string-encoded JSON blob containing the following data sent to the external application: | Data sent | Purpose for the external loyalty system | | --- | --- | | Store ID | To identify the store in which the transaction is being processed via Associate App. This information can be used downstream by the third-party entities as needed. | | Store country | To determine the country where the store is located, where the transaction is being processed. | Example ```plaintext external.integration.app://discount?token%3Dabcdef%26externalIdentity%3Dfghijkl%26cart%3D%7B%22items%22%3A%5B%7B%22productId%22%3A%221000071%22%2C%22itemId%22%3A%228a87355d-5153-44a5-b69e-62fb24f69dad%22%2C%22price%22%3A95%7D%5D%2C%22selectedCoupons%22%3A%5B%5D%2C%22cartId%22%3A%225716d9c8-19b0-47e3-b35b-394fefe10e0d%22%2C%22currency%22%3A%22USD%22%2C%22remainingAmount%22%3A103.44%2C%22grandTotal%22%3A103.44%2C%22subTotal%22%3A99.12%2C%22customerEmail%22%3A%22customer%40newstore.com%22%7D%26store%3D%7B%22storeId%22%3A%22store-123%22%2C%22countryCode%22%3A%22US%22%7D ``` 2. For the webview approach, follow the same process, but the data is exposed on a global object called `window.NEWSTORE` . `cart` and `store` will be contained in `window.NEWSTORE.contextProps`, besides `window.NEWSTORE.securityToken` and `window.NEWSTORE.externalIdentity`. 3. Associate App then waits for your integration to send a callback to Associate App. Use the Associate App `cart.more.loyalty/applyCoupons` URL structure for the callback: 1. *Schema*: `com.newstore.associate-one://` 2. *Domain*: `cart.more.loyaltyProgram` 3. *Path*: `applyCoupons` 4. *QueryParams.coupons*: `coupons[]=couponID-1&coupons[]=couponID-2` 5. *QueryParams.cartId*: `123456` 4. *QueryParams.token*: `abcdef` > [!TIP] > Note > > This token must be identical to the one which NewStore Associate App sent to your application. See this example for the token format > > For example, > > ```plaintext > com.newstore.associate-one://cart.more.loyaltyProgram/applyCoupons?coupons[]=couponID-1&coupons[]=couponID-2&cartId=123456&token=abcdef > ``` ## ## Enabling Associate App to offer loyalty rewards To enable Associate App to be used to offer loyalty rewards to qualifying customers in your business: 1. Use the [Update App configuration](https://docs.newstore.net/api/configuration/apps/associate-app-config-api_config#operation/putConfig) method. 2. In `external_integration` > `cart.more.loyaltyProgram`, specify the following: - In `url`, specify the URL that you have configured for your loyalty rewards application. > [!TIP] > Note > > Do not include the query parameters when specifying the URL. - Set `is_deeplink` to: - `true`: If you are using an external application to provide the loyalty rewards data to Associate App. - `false`: If you are using a website. - For `identity_provider`, specify the relevant value as configured in `post_call_back_urls`. See [Example payload and response](/v1/docs/configuring-loyalty-rewards-on-associate-app#example-payload-and-response). The configured URL for this `identity_provider` is then called with the NewStore authentication token and the external identity information is received in the response payload. > [!NOTE] > Important > > Currently, Associate App only supports a deeplink to an external application. Specifying `false` for the `is_deeplink` property does not allow Associate App to communicate with your external system. ## Sending an identity token to a third-party to integrate with Associate App NewStore provides an option to configure a post-login callback hook in the Associate App. This allows a third party to exchange an identity token issued by NewStore and use it to integrate their native applications with the Associate App, without requiring the user to log in again to the third-party app or website. You must implement an authorization service that accepts a NewStore-issued JWT as input. The service needs to: - Validate the JWT token’s signature to ensure it is genuine. - [optional] Extract the `sub` field from the token and use its value to retrieve any additional user details from the [User Management API](https://docs.p.newstore.partners/#/http/identity-management/users/show-user). - Use the user data to request an authorization token from the internal services. - Return the authorization token to the calling entity. > [!NOTE] > Important > > Please note that all custom claims contained in JWT token are intended for internal use only and are not guaranteed to remain stable. We can only ensure compatibility for standard claims. In Associate App, NewStore ensures that the following is implemented: - Ability to configure the post login callback URL for each tenant - Store the returned token from the third-party server in the session context - Allow the third-party token to be sent as a parameter for the selected deeplink or universal link ### Example payload and response To configure the callback URL for identity forwarding: 1. Use the [Update Associate App configuration method](https://docs.newstore.net/api/configuration/apps/associate-app-config-api_config/#tag/Associate-App-retailer-configuration/operation/putConfig) 2. In `external_integration` > `post_login_callback_urls`, specify the HTTP callback URL(s) that will be called after login. This URL(s) is then called with the NewStore auth token and receives external identity information in the response payload. Example ```json post_login_callback_urls: [ {     "identity_provider": 'vip-loyalty',     "url": "https://vip.loyalty.callback.url.com" }, {     "identity_provider": 'external',     "url": "https://external.callback.url.com" }, {     "identity_provider": 'customer-loyalty',     "url": "https://customer.loyalty.callback.url.com" } ] ``` See the example payload for the callback URL and resulting response with the JWT token: ```plaintext POST /url/of/the/3rdparty/service Content-Type: application/json Accept: application/json ``` ```json {  "deviceId":"xyz”, // any metadata or information about the request origin,  "identity": "Content of the JWT issued by NewStore" } ``` **Response** ```json {  "external_identity":"Content of the 3rd party issued token" } ``` ### Additional considerations To ensure that the solution works, the callback behavior should be configurable: - **Strict** mode - Results in complete login failure if the third-party callback fails - **Optional** mode - Possible callback errors or timeouts are ignored in the background. However, any links to third-parties that require the external identity will fail because of the missing token information. **Related topics** - [Managing order approvals](/v1/docs/using-newstore-associate-app#managing-order-approvals) - [Using NewStore Associate App](/v1/docs/using-newstore-associate-app#assoapp-instorepurchase)