API Reference

💻 Build Point of Sale integration

What you’ll build

This guide illustrates how to build a Point of Sale integration (e.g: Shopify POS, Zelty, LightSpeed).

This guide shows you:

  • How to build the best experience with our loyalty program
  • How to set up authentication, add customers to loyalty programs, handle orders and more

🌟 What a Kiosk Experience looks like with Pongo

The following presents the different capabilities a POS integration must do in order to deliver the best loyalty experience.

Images are often better than words, you can check our diagram here

The Point of Sale experience with Pongo

Merchant Experience (Administration and configuration)

1. A merchant can connect with Pongo from your interface

One of the most important aspect of our experience is to enable our respective clients (a.k.a. the merchant) to connect your software with Pongo autonomously.

For that reason, we developed an Oauth2 authentication System that we host on our server and that you can implement to let the merchant configure by themselves the connexion with Pongo.

You only have to implement the authentication system in your backend and provide a button that redirect to our OAuth form from your admin panel.

👍

Giving the merchant autonomy to connect with Pongo is required to ensure the best security and operational efficiency.

2. How to ensure your system locations and Pongo's location are properly synced

The merchant's locations (or stores in Pongo) are used for many features in Pongo. It is mainly used to understand in which location a customer have been and help them to better engage with them.

All orders sent to Pongo requires a loyalty_store_slug. Once the merchant has linked its Pongo account with your system through Oauth, you can retrieve the list of the merchant's location with the GET stores endpoint.

You will need to make sure the right loyalty_store_slug is passed with the POST create order call.

3. Provide guidance to associate Pongo rewards with POS SKUs

In order to know which product should be added in an order when a customer use a reward, each reward has an external_idattribute. This attribue contains all the SKUs separated by a comma , from external systems.

Those SKUs are added directly in the Pongo backoffice by the merchant on each reward. It is therefore important to tell the merchant and Pongo how to retrieve them.

📘

How to manage external ids / SKUs

  • Each reward has an SKU field where the merchant can add one or multiple external ids.
  • Each SKU/External ID is separated by commas.
  • If the merchant add one SKU, it means it is a single product or menu.
    If the merchant add multiple SKUs, it is a list of product or menu.

🚧

Cautions

  • Ensure the customer choosing a reward corresponding to a product with paid option can choose any options. The options should not be offered to the customer and must be paid.
  • The external_id field can returns multiple SKUs from multiple partner. So you need to filter the SKUs to retains only the one matching in your system.

User Experience on the POS

1. POS Users enlist a customer from the POS

In order to maximize the adoption of our loyalty program by Customers, it is upmost important to give them the possibility to enlist a new customer from the POS system.

To create a customer in Pongo,

A customer can be automatically enlisted if the data are passed with the POST create order call at the end of the process (see Step X) or with the with the POST create order call.

2. POS Users must provide the customer's opt-in option for email and SMS

📘

When a customer enlist to the loyalty program, it is mandatory to ask the customer for their opt-in for Email and SMS communication.

Merchants use Pongo to send marketing communication with their customers and it is utterly important to collect the customers opt-in consent.

Once you collect the customer opt-in options, you can pass it to the POST create order or the POST/PATCH customer calls in the has_optinattribute.

3. POS Users can Identify a customer from the POS and associate it with the order

With the phone number

POS users must be able to find a customer based on their phone number in the POS.

If your POS do not have a customer management system, you can retrieve the data by using our endpoints here

With a digital pass (QR Code or Barcode)

Pongo offers a digital pass Wallet on IOS and Android that allows customer to show a QR code or Bar Code at the store to identify themselves.

The code contains the customer.id that starts by cust_.

If you cannot persist the Pongo customer id in your system. You can retrieve or create a customer by following the documentation here

👍

Use the webhooks to keep your customer base up to date with Pongo

In order to ensure the digital pass identification works, we recommend to subscribe to a Webhook customer.created in order to fetch every new enlisted customer from other connected platforms.

4. Users can see the customer loyalty program details

To deliver the best experience with our loyalty program, POS users should be able to see the following details of their customer's loyalty program:

  • Rewards available on the merchant's program. They can be retrieved from the GET rewards endpoint
  • Distinct, the rewards there are already purchased from the others. You can obtain the rewards purchased by a customer with the GET rewards won by a customer endpoint
  • Total of loyalty points the customer possess. Customers loyalty points are accessible from the GET customer endpoint

5. POS users can redeem a reward from the POS

POS users must be able to redeem a reward for a customer from your POS. To do so, you can use the endpoint POST Buy a reward

⚠️

Make sure the user interface is refreshed to display the rewards purchased by a customer properly

6. POS users can add their customer redeemed rewards to the order

POS users should be able to add a customer redeemed reward to their order from your POS.

Depending on the reward type, you will find:

  • An external_id field for the reward type free_product: it must contain the identification for the product that will be added to the order in your system. This ID can be added on the reward by the merchant in our Dashboard

📘

How to manage external ids / SKUs

  • Each reward has an SKU field where the merchant can add one or multiple external ids.
  • Each SKU/External ID is separated by commas.
  • If the merchant add one SKU, it means it is a single product or menu.
    If the merchant add multiple SKUs, it is a list of product or menu.

🚧

Cautions

  • Ensure the customer choosing a reward corresponding to a product with paid option can choose any options. The options should not be offered to the customer and must be paid.
  • The external_id field can returns multiple SKUs from multiple partner. So you need to filter the SKUs to retains only the one matching in your system.
  • A coupon_code field for the reward type voucher_*: it contains a unique voucher code generated when the customer redeemed the reward. You must create a voucher in your system with the same code and apply it to the order.

📘

The different type of rewards are documented here.

Let us know if your system do not support voucher code or product catalog to deactivate them.

6. Send orders to Pongo

In order for us to attribute the loyalty point to a customer, Pongo must retrieve the order that was closed. To do so, you can use the POST create order endpoint.

👍

Confirm a reward has been used

To confirm a reward has been used by a client, you can pass the Pongo reward_id in the lines object of the Create Ordercall.

Alternatively, if you are not able to indicate if a reward has been used when you send the order to Pongo, you can use the PATCH use a reward enpoint to update the customer's reward status.

🚧

When the order is sent to an external system for payment

If the order is sent to another system for payment and closing (such as a POS), you might have to handle the following scenarios:

  • The system cannot manage the reward (ex: voucher code)
    In that case, customers must be prompt that the rewards will be removed from the order if they don't pay on your system
  • The external system is not able to tell you if the order was successfully closed/paid by the customer
    In that case, do not send the order to our system, the external system will need to be connected with Pongo to ensure the customer can obtain the loyalty points and/or use the rewards.

❗

Ensure the order was successfully closed / paid by the customer before sending it to Pongo. We do not attribute loyalty point to an order that was not successfully paid.

When the order is sent to an external system for payment (like a POS), you can only send the order to Pongo if the system can give you a callback to confirm the order was successfully closed.