An Enhanced Integration (fka Tier 2) enables the following features within your Point of Sale (POS) system:

Redeeming AIQ rewards within your POS
Refund points / redemptions
Loyalty signup within the POS
Redeemable discounts and rewards
Loyalty status indicator in the POS
Loyalty signup information in POS receipts (including QR codes)
Integration with POS's waiting room queue
Real-time loyalty points validation

1. Redeeming AIQ rewards within your POS

Flow:

Integrator calls /api/v2/wallet
Customer selects reward
Integrator calls redemptionURL
Points are immediately deducted

Displaying available rewards

To display available rewards for a customer, make a POST request to the /api/v2/wallet endpoint.

curl -X POST   https://lab.alpineiq.com/api/v2/wallet -H 'content-type: application/json' -H 'x-apikey: SOME API KEY HERE' -d '{
    "phone": "##########", 
    "email": "[email protected]"
}' --compressed

// Use param "badges=true" if you would like us to return the customers badges for Tier 5-7 integration levels. This call is heavy on API though FYI.
// RETURNS 200:
{
    "data": {
        "loyaltyPoints": 1233, // Number of points this contact has
        "hidePointsInWallet": false, // Specifies whether the brand has chosen to hide points from being shown to customer. If true the loyaltyPoints value will always be 0. Most customers use this if they are in a market where points are not allowed per compliance 
        "audiences": [{"name": "VIP", "avatar": "URL to badget image here"}], // this only appears if you pass badges=true as a URL param given it's a heavy API hit
        "discountTemplates": [{ // Array of discounts available for this contact. This is the main section to utilize!
            "id": "string", // Discount ID
            "posDiscountID": "string", // Mapped POS discount ID set by the client within the AIQ discount builder
            "avatar": "string", // Image URL assigned to the discount by the brand
            "name": "string", // Name assigned to the discount
            "pageTitle": "string", // Description about the discount
            "inStoreRedemption": bool, // Specifies whether the discounts from this template should be applied only in-store (ie: used for ecomm integrations). It’s also possible that the discount doesn’t have a dollar or % off value… in that case it is an in-store manual entry type of promo such as a BOGO or exclusive discount like access to exclusive strains. 
            "redemptionURL": "string", // An API URL that client will need to send a PUT request to when the discount is redeemed. Pass param  transactionID=123 if you are a POS
            "priceMin": float, // Minimum order value required to use this discount. Default is 0.0
            "priceMax": float, // Maximum order value allowed to use this discount. Default is 0.0
            "dollarValue": float,
            "percentageValue": float,
            "disableStacking": bool, // prevents stacking in (IE: Blaze/ Tymber environments)
            "pointsDeduction": float // The number of loyalty points that will be deducted as a result of using this discount
        }]
    },
    "code": 200,
    "success": true
}

Important Fields:

posdiscountid: Mapped POS discount ID set by the client within the AIQ discount builder.
name: Name assigned to the discount.
pagetitle: Description about the discount.
redemptionurl: API URL to call when the discount is redeemed.
pointsDeduction: The number of loyalty points that will be deducted as a result of using this discount

Other fields:

discountTemplates: This an array of discounts the user has access to at the current time.

Note:

Use the badges=true parameter if you wish to return the customer's badges for tiered integration levels.
This call can be resource-intensive; use it judiciously.

Some integrations simply apply a dollar or percentage discount (mutually exclusive) to the cart and call our redemption URL once the checkout is complete. However, more advanced integrations allow AIQ to segment rewards within your POS, enabling powerful combinations like BOGO offers or product-level specific discounts. AIQ leverages this segmentation to determine which discounts are available at any given time.

How to Handle Discounts:

Step 1: Ensure the discounts in your POS are also set up in AIQ. The client will either manually input the POS discount ID into AIQ’s discount creation system or use AIQ’s GET endpoint to sync discounts.
Step 2: When creating the cart, call our GET endpoint and filter out discount templates based on matching posDiscountID values. Only discounts available for that customer at that time will be returned.
Step 3: Once the cart is completed and paid for, call our PUT endpoint (redemption URL) for each redeemed discount, appending the transaction ID to the URL parameter (transactionID=123). This is crucial for reporting and tracking rewards, especially for public entity CFO reports.

Example:

If the POS offers 2 discounts, AIQ assumes they are already configured within your system. Discounts with matching posDiscountID values will be displayed as available to the customer. Discounts not applicable at the time will not be returned in the response.

Stacking Behavior

Each discountTemplate includes:

disableStacking (boolean)

If:

disableStacking = true → This reward cannot be combined with other rewards.

disableStacking = false → This reward may be combined with other stackable rewards.

There is no system-level maximum cap on the number of stackable rewards applied, provided:

The customer has sufficient points
Cart subtotal remains positive
All priceMin / priceMax conditions are satisfied

Cart Recalculation Rule

priceMin and priceMax refer to the current cart subtotal.

If:

A reward is applied
The subtotal decreases
The new subtotal falls below another reward’s priceMin

That other reward may no longer be eligible.

Integrators should dynamically re-evaluate eligibility after each reward application.

Company & Multi-Store Behavior

API credentials are company-based.
Points are tracked at the company level (not per store).
A customer’s points are shared across all stores under that company.
Discounts may be segmented by store, so available rewards may differ depending on store context.

Reward Types

AIQ supports:

Static dollar discounts
Percentage discounts
Manual in-store discounts (BOGO, exclusive access)
Tier-based rewards

AIQ does NOT support:

SKU-specific discount enforcement at the API level. SKU-level restrictions must be handled within the POS system.

2. Refund points / redemptions

This endpoint should not be implemented by clients directly. It is intended for POS or ecommerce integration partners only.

In some cases, you may want to show rewards before calling the redemption URL for each discount. For example, if a customer returns a purchased item (e.g., a T-shirt) after the transaction is completed, you may need to reverse the points granted. Similarly, for failed transactions where the POS checkout process must be restarted and rewards reapplied, you cannot reuse the same points until the previous redemption is refunded.

To refund or delete a redemption, call the following endpoint:

Endpoint to Refund Redemption:

URL: /api/v1.1/discount/redeem/:uid/:contactID/:templateID/:rid
Method: DELETE
Purpose: Permanently delete a discount redemption

If using Model B (POS-driven redemption): No refund call is needed unless POS already executed redemption.

3. Loyalty signup within the POS

To sign up a new member for loyalty, make a POST request to the /api/v2/loyalty endpoint:

curl -X POST   https://lab.alpineiq.com/api/v2/loyalty -H 'content-type: application/json' -H 'x-apikey: PeArOcIfWGA9MC9mtSbRmuiZ60Dl0xxcgQ9vL4CBboWw7Kz92aKcs4M1xg' -d '{
    "firstName": "Shahzil",
    "lastName": "A",
    "mobilePhone": "##########",
    "email": "[email protected]",
    "address": "200 Santa Monica Pier, Santa Monica, CA 90401",
    "favoriteStore": "Store1",
    "loyalty": true,
}' --compressed

Notes:

Required Fields: Ensure that email or phone are provided to comply with opt-in requirements. If additional customer details such as first name, last name, and store location are needed, these can be passed as hidden inputs in the request.

Store Location: When a new JSON value for store location comes in, AIQ will map these locations in the dashboard, helping track where the customer signed up.

Consent Text: Include consent text for the customer that the clerk must sign off on. This ensures legal compliance, and the consent text should look something like this:

By signing up, I consent to enroll in the member list, understanding that I will receive marketing communications, including, but not limited to, advertisements, through text messages, calls either through an automatic telephone dialing system or artificial or prerecorded voice call, emails, or other outreach channels. By doing so, I understand that I am allowing {{clientName}}, and it's technology provider AIQ, Inc. to retain my personal contact details and engagement history for use in personalized marketing communications. I understand that I may opt-out of text messages at any time by replying "STOP". Standard messaging and calling rates may apply. I affirm that I am of legal age to receive communications related to the services and products being advertised. Consent is not a condition of purchase.

A member may want to receive messaging without accruing loyalty points. For 99% of use cases, set "loyalty" = true. Please note that AIQ should be trusted as the source of truth for opt-ins to marketing for mutual clients. AIQ tracks signup and opt-in confirmations across multiple synced integrations, including website, third-party services, first-party ecommerce, native POS, mobile QR codes, mobile apps, tablets, and text-to-join.

Visual example:

4. Loyalty signup information in POS receipts (including QR codes)

Include loyalty signup information in your POS receipts to encourage customer engagement.

Note:

This can be achieved by integrating QR codes or URLs that direct customers to the loyalty signup page or their wallet.
For example:
- https://lab.alpineiq.com/joinmembers/{{uid}}/
- https://{{uid}}.aiqapps.com/w/login
- Replace {{uid}} with your AIQ account's UID.

5. Integration with POS's waiting room queue

If your POS has an integrated waiting room queue API, provide that API to AIQ's engineering team.

Note:

This integration allows AIQ to power in-store personalized experiences based on machine learning-derived recommendations.
For example, if a majority of customers in the store are edibles buyers, AIQ can adjust in-store screen menus to prioritize edibles
We can also show your live queue in our Staff View

6. Real-time loyalty points validation

To verify if exact earned loyalty values can be shared in real-time, make a GET request to the /api/v2/loyalty/default/:uid endpoint:

Response Example:

"data": {     
"accrual": 100,     
"rounding": {       
"start": 1754413505,       
"option": 3     },     
"maxVisitsPerDay": 1,     
"perVisit": 100,     
"optInsForLoyalty": {       
"start": 0,       
"browser": false,       
"email": false,       
"push": false,       
"text": false,       
"voice": false,       
"allRequired": false,       
"resetPoints": false     
   }   
 },   
"code": 200,   
"success": true

Note:

The accrual field indicates the number of points per $100 spent.
- Example: If this field as 100, this means it is one point per dollar spent.
The rounding field specifies the rounding behavior for points.
- start the time/date that rounding is set to start
- option
  - 1 - Nearest Dollar
  - 2 - Round Down
  - 3 - Round Up
The maxVisitsPerDay field indicates the maximum number of visits a customer can get points applied to per day.
The perVisit field indicates the number of points a customer gets per visit instead of per sale.
The optInsForLoyalty field specifies the opt-in requirements for various communication channels.