GonnaOrder Help Center > Manage Integrations > Integrate GonnaOrder Vouchers & Loyalty Scheme with POS Via API

Integrate GonnaOrder Vouchers & Loyalty Scheme with POS Via API

GonnaOrder provides highly versatile digital vouchers and a loyalty system that you can integrate with your preferred POS provider. This gives you a more convenient way to use GonnaOrder’s digital vouchers and loyalty scheme. All this is possible thanks to GonnaOrder APIs that allow POS systems interact and use digital vouchers and loyalty mechanisms. This documentation provides a guide on how a POS can integrate and use GonnaOrder’s digital voucher and loyalty scheme.

On this Page

Configure POS Parameters

To get started, it is highly recommended that you configure several parameters in your POS for each store for calling the GonnaOrder APIs, triggering the loyalty flow. Here are the POS parameters that you should configure in the POS.

GonnaOrder API Base URL: https://api.gonnaorder.com/. This base URL calls the GonnaOrder backend APIs.

GonnaOrder username. It’s used to get the bearer token for all GonnaOrder APIs.

GonnaOrder password. Used for getting the bearer token for all GonnaOrder APIs.

GonnaOrder Store id. It is an integer number for calling the APIs (e.g., 1234).

GonnaOrder Loyalty Enabled – Yes / No. If this setting is set to Yes, then the POS follows the voucher flow with validate voucher against the GonnaOrder API and publish the order to GonnaOrder.

Authorize the API

The POS system must authenticate before calling the GonnaOrder API to request a token that is passed in every API header. For API authorization to be successful, use the GonnaOrder username and GonnaOrder password mentioned in the POS parameters section above. See related documentation.

Authorization Request

POST: https://admin.gonnaorder.com/api/v1/auth/login

{
	"username":"user",
	"password":"password"
}

Response

„Authorization“: „Bearer {ACCESS_TOKEN}“

Get Available Vouchers API for an Existing Member

The Get available vouchers API allows the finding of available vouchers for a member based on their member code or telephone number. Upon request, it returns all available vouchers associated with the specific member and their properties.

In cases where the voucher code is known and the user wants to redeem the voucher, the POS can skip the Get available vouchers API. Instead, utilize the Validate voucher API directly.

Note that the Get available vouchers API does not return the consequences of a voucher on an order. This is because the input does not include any order details. Therefore, it’s crucial to call the Validate voucher API to get the correct consequences of the order. For instance, a voucher may be of 10 EUR but the order may be of 5 EUR. In this case, the voucher cannot be consumed fully.

What You Need to Send a Get Available Vouchers API Request

The user must provide at least one of the following parameters – member code or phone number. If the user provides both parameters, the system looks for a match with both parameters. However, in cases where there are multiple results due to data pollution, the system returns the first result.

  • memberCode: The loyalty code (GonnaOrder loyalty voucher id).
  • phoneNumber: The customer’s mobile number. Use the international mobile number format with the international code and no spaces (e.g., +301234567890).
  • searchString: This is the string used to search for the customer’s member code and phone number. First, the system conducts a search based on the member code. If not found, it will check the format of the string. If there is no result found and the string does not start with +, it will add the international phone code of the country of the store and then trim the spaces of the phone number and search by phone number. For example, the search string “6987 482018” converts to “+30698748018”.

Sample Request

GET: https://api.gonnaorder.com/api/v1/stores/{storeId}/loyalty/customer-vouchers?memberCode=XYZ&phoneNumber=+302310589248

  • XYZ is the member code and +302310589248 is the phone number.
  • Replace storeId with your store ID, a numerical value that is available in your store URL. See the image below
Finding Your GonnaOrder Store ID
Finding Your GonnaOrder Store ID

If the member is found with vouchers available, the API will respond with the following:

Response – Member Found with Vouchers Available

{ 
   "name":"John Doe", 
   "phoneNumber":"+302310589248", 
   "email":"john@gonnaorder.com", 
   "memberCode":"xyz", 
   "vouchers":[ 
      { 
         "code":"xyz", 
         "discount":5.50, 
         "source":"LOYALTY", 
         "discountType":"MONETARY", 
         " description ":"GonnaOrder Monetary Loyalty Voucher" 
} 
   ] 
}

If the member is found and they have no digital vouchers or loyalty vouchers available or have vouchers with zero balance, then the API will send the following response.

Response – Member with No Vouchers Available or Has Vouchers with No Balance

{ 
   "name":"John Doe", 
   "phoneNumber":"+302310589248", 
   "email":"john@gonnaorder.com", 
   "memberCode":"xyz" 
}

When the member found has multiple vouchers, the API will give the following response.

Response – Member Found with Multiple Vouchers

{ 
   "name":"John Doe", 
   "phoneNumber":"+302310589248",
   "email":"john@gonnaorder.com", 
   "memberCode":"xyz", 
   "vouchers":[ 
      { 
         "code":"xyz", 
         "discount":40, 
         "source":"STORE", 
         "discountType":"PERCENTILE", 
         "description":"GonnaOrder Percentile Store Voucher" 
      },
      { 
         "code":"DISCOUNT", 
         "discount":10.50, 
         "source":"STORE", 
         "discountType":"MONETARY", 
         "description":"GonnaOrder Monetary Store Voucher"
      } 
   ] 
}

However, if the member is not found in the system, then the API will respond by informing the user about the same.

Response – Member Not Found

  "member not found"

Validate Voucher API

When a user enters a voucher code in the POS that has GonnaOrder loyalty active, the POS will call a GonnaOrder API to understand the consequences of using the voucher. The user may enter the voucher directly as part of the screen or select it based on the previous response of the Get available vouchers API.

The following are the output parameters of the validate voucher API.

Indication if the voucher is valid or not

Voucher object with voucher value or voucher percentage: this is the value that the user can consume. The POS will use it directly.

Order object with the impacted consequences from the voucher. The POS can use it or calculate it based on the voucher.

Requirements for Validate Voucher API Request

For the Validate voucher API request to be successful, users must provide both the voucher code and order value (non-discounted price)

  • voucherCode: This is the voucher code as entered by the cashier or user. It can be based on typical store vouchers or loyalty vouchers.
  • orderValue: This is the total order amount without considering any discounts offered. It may impact the voucher logic and is used to communicate the discount order value.

POST /api/v1/stores/{storeId}/customer-voucher/validate/order

{ 
   "voucherCode": "{voucherCode}", 
   "totalNonDiscountedPrice": {price} 
}

Here is an example of such API request.

Sample Request

POST: https://api.gonnaorder.com/api/v1/stores/155/customer-voucher/validate/order

{
	 "voucherCode" : "xyz", 
         "totalNonDiscountedPrice":200
}

Response for Loyalty Monetary Voucher

If the voucher is a loyalty monetary voucher that gets reloaded with credit and serves as a wallet, then the API will return the following response.

{
      "active":true, 
      "voucher":{ 
      "code":"xyz", 
      "discount":5.50, 
      "discountType":"MONETARY", 
      "description":"GonnaOrder Monetary Loyalty Voucher", 
      "source":"LOYALTY" 
   }, 
   "order":{ 
      "totalNonDiscountedPrice":200, 
      "voucherDiscount":5.50, 
      "totalDiscountedPrice":194.50 
   } 
}

Response for Store Monetary Voucher

A store monetary voucher is one created by the store owner and is deducted directly from the order value in monetary form. If the voucher is a store monetary voucher, then the API will return the following response.

{ 
   "active":true, 
   "voucher":{ 
      "code":"xyz", 
      "discount":3.50, 
      "discountType":"MONETARY", 
      “description”:”GonnaOrder Monetary Store Voucher” 
      "source":"STORE" 
   }, 
   "order":{ 
      "totalNonDiscountedPrice":200, 
      "voucherDiscount":3.50, 
      "totalDiscountedPrice":196.50 
   } 
}

Response for Store Percentage Voucher

As the name suggests, a store percentage voucher deducts a certain percentage of the order value as discount. In this case, the API will return the following response.

{ 
   "active":true, 
   "voucher":{ 
      "code":"xyz", 
      "discount":10, 
      "discountType":"PERCENTILE", 
      "description":"GonnaOrder Percentile Store Voucher", 
      "source":"STORE" 
   }, 
   "order":{ 
      "totalNonDiscountedPrice":200, 
      "voucherDiscount":20, 
      "totalDiscountedPrice":180 
   } 
}

Response for Voucher Not Valid or Without Balance

If a voucher is invalid or has no remaining balance (zero balance), the API will return the following response. 

{ 
   "active":false
}

Process External Order API

You can process external order API on your POS with GonnaOrder. When an order is sent to the POS, the POS calls a GonnaOrder API to consume the voucher and process the order. Therefore, GonnaOrder will deduct the discount applied on the order from the voucher and add loyalty points to the member code.

Input Parameters

The following are the input parameters required to process external order API.

External order id: An order ID as used by the POS.

Voucher code: This is the store or loyalty vouchers‘ code. It will be used to redeem points.

Member code: The member code selected (optional). This will be used to collect points. In case the voucher code used is a loyalty voucher, then the member code is not necessary.

Total Non-discounted price. This is the total price without the voucher discount.

Total discounted price. This is the price of the order including the discount.

Total discount: This is the price or value of the voucher.

Request

POST: /api/v1/stores/{storeId}/external-order

Here is an example of API request to process external order API.

Sample Request

POST: https://api.gonnaorder.com/api/v1/stores/203/external-order

{
	   "externalOrderId":5968,
           "voucherCode":"xyz", 
           "memberCode":"abc", 
           "totalNonDiscountedPrice":200, 
           "totalDiscountedPrice":180, 
           "totalDiscount":20 
}

Response

The API may return one of the following responses.

  • If success, the status 201 is returned without a response body
  • If failure, the status 500 is returned without a response body

API Business Logic

To process external order API, the GonnaOrder API follows the following business logic based on each scenario.

  • If the external order does not have a voucher and does not have a member code.
    • Then simply same the order.
  • If the external order has a voucher.
    • Then follow the logic to reduce the voucher value if applicable for the voucher type based on discount given by the POS. This should ideally be the same as the discount the voucher would apply to the total non-discounted price. But in this case the logic considers the total discount given by the POS as master.
  • If the external order has a member code OR the external order has a loyalty monetary voucher.
    • Then collect points automatically for this member code OR for the loyalty monetary voucher based on total discount price
  • If discount given by the POS is high than the loyalty voucher value.
    • Then the loyalty voucher value is set to 0 (and not negative). In this case, the customer may have received a higher discount than what should be in the POS.

If the POS does not submit the total discounted price and total discount, then GonnaOrder will calculate it based on the voucher properties and deduct the voucher value based on this.

Process GonnaOrder Orders Business Logic

If an order is submitted by GonnaOrder, is authenticated, and the order has a loyalty voucher, GonnaOrder collects points for a user in a store that has loyalty enabled.

In addition to this logic, the system will also collect points automatically if the order is not authenticated but the voucher is a loyalty voucher. In this case there is no need for authentication to collect points. The system will both collect points and redeem points in this case