API Reference

📲 Build an order system integration (Click & Collect, Order & Pay)

What you will build

This guide describes how to develop an integration for Order & Pay solution (e.g.: Sunday, Qodeup) or Click & Collect (e.g.: Dood)

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
  • The requirements we look at for our Quality Assurance review

🌟 What a good Order & Pay or Click & Collect Experience looks like

The following presents the different capabilities a C&C or Order & Pay integration must do in order to deliver the best loyalty experience.

Images are often better than words, you can check our prototypes for:

  • Order & Pay experience here
  • Click & Collect here

📘

For Order & Pay app that offers payment module only

For the Order & Pay system (like Sunday) that offers to manage payments only, please refers to the guide to Build a payment terminal integration

Merchant Experience (Administration and configuration)

Follow the guide here

Customer Experience

1. Customers can enlist / identify themselves within your app

In order to maximize the adoption of our loyalty program by Customers, it is upmost important to give them the possibility to enlist from your app.

Customers enlist or identify themselves with their phone number only.

You can find all the documentation to retrieve or create a customer here

👍

At the beginning of the ordering experience, Customers should have the possibility to authenticate in order to access their loyalty program details and rewards.

Think about the experience to be like the one on a kiosk at MacDonalds for exemple.

2. Customers must provide their 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. Identified customers can see their loyalty program details

To deliver the best experience with our loyalty program, Customers should be able to see the following details of their loyalty program:

  • Rewards available on the merchant's program. They can be retrieved from the GET rewards endpoint
  • Total of loyalty points the customer possess. Customers loyalty points are accessible from the GET customer 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

4. Identified customers can redeem a reward from your app

Customers must be able to redeem a reward from your app. 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

5. Identified customers can add their redeemed rewards to the order

Customers should be able to add a redeemed reward to their order from your app.

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.