Make Your First POS API Call

The information provided on this page allows developers to make API calls to the Punchh server in production and test environments.

Authorization

A combination of the API key (i.e., location key) and business key needs to be passed in the Authorization header to make API calls. For example:

Authorization: Token token=LOCATION_KEY_GOES_HERE, btoken=BUSINESS_KEY_GOES_HERE

If you do not have these keys, reach out to your Punchh representative for further assistance.

If you already have the location key or business key and you know which environment each key belongs to (production or testing), you can make your first API request.

User Agent

All API requests MUST include a valid User-Agent header. This allows Punchh to contact you if there are problems. Requests with no User-Agent header will be rejected.

User Agent Format

The integrator should include the Integrator/Vendor/Agency Name, Integration type (POS/Kiosk/OnlineOrder/Mobile/Web/SystemIntegrator/Middleware), and Integration Version Number in the User-Agent header in the following format.

IntegratorName/IntegrationType/VersionNumber

Example User Agent

NCRSilverPro/POS/3.5.6b

Base URIs

Please reach out to your Punchh representative in order to receive the sandbox and production base URLs that you should be using in order to consume the Punchh APIs.

Required Parameters

Required parameters are passed in API calls as shown in the following example.

$ curl "https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/locations/configuration"
-H 'Authorization: Token token=LOCATION_KEY_GOES_HERE, btoken=BUSINESS_KEY_GOES_HERE'
-X GET

Testing Your Integration With iFrame

Punchh provides a loyalty iFrame URL that you can use to test the POS integration with the Punchh server in a testing environment. If you do not have the iFrame URL, reach out to your Punchh representative for further assistance. You can create a test user account on iFrame and use this account to 1) perform test check-ins and redemptions, and 2) develop and test other features. The same user can be used for all of the iFrame URLs provided. You can also generate a redemption code using iFrame.

To test whether the barcode is working properly, you can use the iFrame account to enter the barcode that you generated when performing the check-in on the test account. Barcodes are generated using short_key, which is returned by the Location Configuration API. You can create check-ins using those barcodes on iFrame.

User Search Keys

The User Look-up and Fetch Balance and Create Check-in API requests require one of the following fields to work as expected. Rules to identify various search keys supported by Punchh are also mentioned.

Check-in Workflow

A check-in essentially records the loyalty user’s visit along with order details (such as menu items ordered, prices, etc.). For creating a check-in at POS, the user is asked to provide any one of the following:

• Email address
• Phone number
• Card number
• Redemption code
• QR code
• Apple NFC token

A check-in is then processed using any one of the following:

Checking if the guest has an existing loyalty account

For this purpose, the POS makes a User Look-up and Fetch Balance API call to the Punchh server that returns either of the following responses:

• User not found: In this case, the ‘User Not Found’ error is returned. The guest is then registered, for which the POS makes the Create User API call to the Punchh server to create a loyalty account for the user. The order is then taken from the guest user, and a loyalty check-in is created for which the POS makes the Create Check-in API call to the Punchh server.

• User found: In this case, the guest user's loyalty account details are returned. The order is then taken from the guest user, and a loyalty check-in is created for which the POS makes a Create Check-in API call to the Punchh server.

Directly creating a loyalty check-in

The POS makes a Create Check-in API call to the Punchh server. If the user does not have an existing loyalty account, the call will fail with the "HTTP 404 - not found" response code.

Redemption Types

Redemption is a discount that can be applied to an order. While ordering at the POS, loyalty guests can request to redeem rewards (available in their account) on the current order. The reward offers are configured by the business. For example, the amount of a loyalty guest's order is $8 and the guest's account contains $10 as redeemable. At the POS, the guest redeems $8 from the account and applies it to the order. This reduces the final amount of the order to $0 and leaves $2 as redeemable in the guest's account.

The user object provides information regarding every possible balance the user may have. It may not be possible to determine which type of redemption should be available for the user. So a configuration is needed on the POS vendor side to determine which type of redemption should be available for the entire business based on the program type information returned in the Program Meta API call.

Punchh supports different kinds of discounts depending on the loyalty program configured for the business (see Punchh Offers and Program Types). What type of discount will be available to a loyalty guest depends on the loyalty program chosen by the business. The following table lists the kinds of discounts that Punchh supports through various loyalty programs.

Redemption Workflow

When creating a redemption, the POS makes a Possible Redemptions API call to the Punchh server, which returns a response that tells if a particular redemption is possible on the given order in the context of the loyalty guest account.

If the redemption can be applied to the current order, the POS makes a Create Redemption API call to the Punchh server to apply the redemption and settle the order. As a result, the redemption amount gets deducted from the loyalty guest's account balance.

Under exceptional circumstances, if it is required to cancel the order and roll back the redemption, the POS makes a Void Redemption API call to the Punchh server. Redemption is accordingly rolled back, and rewards are restored to the user’s account, a process which consumes some time.

Things To Remember While Applying POS Discounts

1. Discounts are ideally passed as either a 'D' type item or a negative value of 'M' type in the case of voiding a discount.

2. In the case of voiding a discount, it cannot be sent as a “D” item type since the discount is always deducted from the actual receipt amount and taken as negative. In order to reverse or void the discount, the POS needs to send the same item with item type as 'M' or some other, but not as 'D' type.

3. The POS should only show the final discounts applied on the receipt that is sent to the Punchh server.

Things To Remember While Applying Transaction Reversals at POS

1. After check-in, edits are possible for a check only if the pending points feature is enabled for the business.

2. For voiding Punchh discounts: In order to void a redemption, the POS makes a Void Redemption API call to the Punchh server. Then the Possible Redemptions API returns the available redemptions that can be applied as requested by the user.

3. For voiding menu items and non-Punchh discounts: This can be done if the business allows it on the POS side. The receipt will have only those items that have been actually purchased by the user and only those redemptions that have been applied at the time the check is closed. If any menu item needs to be updated, then the first receipt needs to be voided and then updated via the Store Receipt Details From POS API by sending the status as void. Once the check is closed, it gets updated in ISL.

4. In the case of auto check-in, for any reversals the receipt needs to be cancelled in order to void check-in first, and then redemptions need to be voided to apply any other redemptions if required.

Best Practices

1. Use the category (item, family, major) as numeric IDs, which would not change on the POS systems unless and until the business decides to do so.

2. If one menu item needs to be part of multiple family/major groups, then different item IDs should be used.

3. When an item is sent to Punchh, the major/family group for any single menu item will always be a singular value in the field. If the business ONLY has a single layer of functionality, then a business should set BOTH major/family groups to the same value while passing the request to the Punchh server.

4. Generically, every menu item belongs to a family group. A family group is a sub-category of a major group.

POS APIs at a Glance

• User Control: Registers a user or fetches account details of a registered user

  • User Look-up and Fetch Balance
  • Create New User

• Check-in Control: Creates a check-in

  • Create Check-in

• Redemption Control: Checks if an offer can be redeemed, creates a redemption to redeem an applicable offer, and cancels a redemption

  • Possible Redemptions
  • Create Redemption
  • Void Redemption

• Store Receipt Details: Stores an order's receipt details in ISL

  • Store Receipt Details From POS

• Location Configuration: Retrieves the location configuration of a POS store and the loyalty program configurations for the business

  • Location Configuration
  • Program Meta