Omnichannel: Store Associate Managed Loyalty (POS loyalty interface)
- DarkLight
Omnichannel: Store Associate Managed Loyalty (POS loyalty interface)
- DarkLight
Article summary
Did you find this summary helpful?
Thank you for your feedback
One of Yotpo's In store solutions is integrating with the Point of Sale in order to create a flow that is built on top of the POS itself. This integration requires building into the Point of Sale UI so that it is able to show the customer's point balance and reward options. With this integration, your customers can:
- Earn points for purchasing in-store (in addition to online).
- Redeem existing points to get discounts in-store.
- Create a loyalty account in the store.
- Get discount rewards to use in the store.
In-store customer flow
When the customer walks into the store, they have minimal actions to do. The actions are all done by the store clerk. All the customer needs to do is give their email/phone number
. 
Please note:
This integration requires dev experience. We recommend working with developers that know how to work with the specific POS system.
How the integration works
The POS loyalty integration includes data flows from and to Yotpo. 
Step 1: Show customer details in the POS
In order to show the customer details on the POS customer page, the POS needs to use our Fetch Customer Details endpoint. This endpoint needs to receive the customer's email or customer phone number and it will then return the customer's point balance and VIP tier status. 
Step 2: Create in-store reward options with Yotpo
In order to present rewards within the POS UI, first Yotpo needs to know these reward options.
There are two types of reward options that can be used for associate-led POS integrations:
Custom Coupon - manually pre-uploaded to Yotpo in batches via API
- This is a reward option that allows you to redeem points for fixed-amount discounts only. The codes need to be pre-uploaded into Yotpo via API in batches, per discount increment (the specific reward redeemed will be returned in the response to the API call made to create a reward, and will need to be sent back to Yotpo in the API call to create an order).
- No Delayed Point Deduction - Points for custom coupons are always deducted as soon as a discount is redeemed, therefore if you chose to take this route, we recommend adding a ‘redemption reversal’ button in your UI (and automatically reversing orders for abandoned checkout), by retrieving the “point_redemption_id” by calling the Get Redemption Code Data endpoint and then using this ID to call the Approve Redemption Cancellation endpoint.
To use Custom Coupon rewards for associate-led POS integrations, follow these guidelines:
- If you’re a merchant on Shopify or Shopify Plus, refer to our Creating a Redeemable Custom Rewards in Shopify article.
- If you’re a merchant on any other platform or generic, refer to our Creating a Custom Coupon article.
Generic Redemption - automatically generated by Yotpo at the time of redemption
If you’re looking for an automated process for your in-store rewards, you can use Yotpo’s generic fixed amount and variable reward options.
NOTE: If you’re a merchant on Shopify or Shopify Plus, please contact Yotpo support to use this reward option.
- These are rewards that allow you to redeem points for fixed and variable amount discounts. In this case, the codes do not need to be pre-uploaded into Yotpo, instead, they are created randomly by Yotpo when the reward is redeemed (the coupon code is returned in the API response). In this path, you will need to receive the discount code returned by Yotpo and make it available in the POS platform, so it can be applied to the purchase (and later sent to Yotpo in the API call to create an order).
- Delayed Point Deduction - You can set the “delayed_point_deduction” field to true when redeeming points, which will mean that Yotpo will not deduct the points from the customer’s balance until the reward is received in an order (via API). This allows you to spare the need to cancel rewards that are unused, however, you will need to listen to Yotpo’s reward cancellation event to the URL you provide to the merchant. These events will fire each time a customer tries to create another reward with typer delayed point deduction.
NOTE: This is required to prevent fraud. 
Learn more about generic redemptions
Important!
Whether or not using Delayed Point Deduction, the reward returned in the response to the redemption via API must be sent back to Yotpo in the order.
Step 3: Present available reward options for a customer in the POS UI
In order for the clerk to see the available redemption options for the specific customer on the POS itself, the POS needs to use our Get Available Redemption Options endpoint. This endpoint needs to receive the customer's email/phone number. The endpoint will return all of the relevant redemption options. The POS needs to present the name of the redemption option. If you only want to get offline redemptions in this API call, use the parameter "is_offline". 
Step 4: Create a reward via API once the clerk redeems points
Once the clerk clicks on one of the reward options, the POS needs to create a new redemption on Yotpo's side with the Create Redemption endpoint. This endpoint receives the customer's email/phone number and the redemption option id. It will then deduct the points for the customer.
Step 5: Send Yotpo order data
Once the order is placed on the POS, the order information needs to be sent back to Yotpo with the Create Order endpoint.
The order information needs to include three parameters:
- Order information - order ID, the total amount in cents, order status, and currency code are required.
- Discount information - The discount code that was used with that order.
- Customer email - Customer email must be passed in each order for Yotpo to correctly identify the customer and reward points to their point balance (this email needs to be the same as the customer uses in their eCommerce platform account for points to accumulate across both systems).
Platform-specific settings
Order statuses may vary in accordance with the eCommerce platform you're using.
To make sure the settings match your platform, go to the Settings section of your Loyalty admin and check which order status is configured. Match the parameter of the Create Order API call to the status set in your Yotpo account in order to allow our system to reward/deduct points accordingly.
Choose the platform relevant to you in order to learn how to do that:
Shopify
If you are setting up this generic POS integration on a Yotpo Loyalty & Referrals account connected to Shopify, there is no need to send us the order status. As soon as the order is sent, points will be given and the order will be processed.
You will be able to see the order details in the customer's profile.
BigCommerce
If you're using BigCommerce, the order should be sent with a status parameter matching the setting you have in your Yotpo Loyalty admin:
- Any PAID Status = completed
- Awaiting Fulfilment = awaitingfulfillment
- Awaiting Shipment = awaitingshipment
- Awaiting Pickup = awaitingpickup
- Partially Shipped = partiallyshipped
- Shipped = shipped
- Completed = completed
For example, when using the "Any PAID status", the API call should look like this:
Adobe Commerce (Magento)
In your Loyalty & Referrals admin, the Process Order With Status (regex) field needs to match the status sent from Adobe Commerce (Magento), as configured at the point of integration.
Salesforce Commerce Cloud (SFCC)
If you're using SFCC, the order should be sent with a status parameter matching the setting of your Yotpo Loyalty admin:
- CREATED = 0
- NEW = 3
- OPEN = 4
- COMPLETED = 5
- CREATED or NEW = 0
- CREATED, NEW or OPEN = 0
- CREATED, NEW, OPEN or COMPLETED = 0
For example, when using the "CREATED" status, the API call should look like this:
Generic/custom integration
In your Loyalty & Referrals admin, the Process Order With Status (regex) field needs to match the status sent from your platform, as configured at the point of integration.
Order information
Customer information
Discount information
- Delayed point deduction - If you chose to use the generic fixed or variable reward option (above) you may set this field as “true” to deduct points only when a redemption was actually used in an order. Yotpo must have the discount information in the order for us to know that we need to deduct points for the customer. Until the points are actually deducted, they will remain in the customer’s balance, and in case the customer tries to use the same points for another reward Yotpo will fire a cancellation event to notify you to no longer accept the pending reward.
- Reporting - We use the discount information in the order to know that the customer really used the redemption and then we are able to properly report on redeeming customers and other relevant metrics.
Step 6: Send Yotpo refund data
Refund data is important because usually, brands want to deduct the points that the customer received for a purchase if that purchase was returned and refunded. In order to retroactively deduct points for a refunded purchase in-store, we need to get refund data via the Create Refund endpoint. The refund data must include two parameters - order id and refund amount (total amount cents). We use the order id to find the specific order (and customer) that earned the customer points/tier status/etc. This is how we are able to reverse these actions. Email is not required since the ID is enough for us to learn all of the information directly from the order.
Important!
If a customer is returning an item that was bought online, but the refund was made in-store, the order ID in this case needs to be the online order id. Otherwise, Yotpo will not be able to remove the points for that purchase
Was this article helpful?
