Common use cases
POS Integration Tiers
Enhanced Integration
17 min
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 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\@gmail com" }' 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 2\ refund points / redemptions 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 this endpoint should not be implemented by clients directly it is intended for pos or ecommerce integration partners only 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" "shahzill\@aiq com", "address" "200 santa monica pier, santa monica, ca 90401", "favoritestore" "store1", "loyalty" true, }' compressed notes required fields ensure that email and 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 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 //lab alpineiq com/wallet/{{uid}}/ 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 docid\ fcovqd0g02j6dkcklhenf 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 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 if aiq cannot provide exact earned loyalty values in real time, use estimated points as a fallback estimated points can be calculated based on the accrual and pervisit values retrieved from the /api/v2/loyalty/default/\ uid endpoint ensure that your pos system is configured to handle estimated points appropriately this will only include the stores default settings and does not include any multiplers that have been added if they fall into a specific audience