Overview

Coupontools API: simple & powerful

Connect our Coupontools platform with your apps or web projects. The Coupontools REST API allows you to query metadata about your account, campaigns, validations, usage data, and many more. Use the Coupontools API to integrate coupons directly into your website or app. Coupontools and your app will communicate by sending HTTP requests back and forth.

This page provides an overview of the Coupontools API. The topics in this chapter deal with several specific aspects of the API.

If you have any questions about integrating our API, don't hesitate to get in touch with us. We are happy to help!

Definitions

Coupon

A coupon is the layout/settings for one campaign for one business. Our platform generates and assigns a unique URL for each coupon in order to distinguish between different coupons. Example coupon URL: https://digicpn.com/p/vuhykb where "vuhykb" is the unique identifier for the coupon. When shared between consumers, each consumer will get a unique coupon (= coupon session).

Coupon session

Every consumer who opens or receives a coupon will have a unique URL assigned. When opening a coupon URL (f.e. https://digicpn.com/p/vuhykb), the system will automatically generate a unique coupon session and append it to the back of the URL. Example coupon session URL: https://digicpn.com/p/vuhykb/ac6s7u3g8a25ja7x9qg87 where "ac6s7u3g8a25ja7x9qg87" is the unique coupon session. When shared between consumers, each consumer will get the same coupon session. Meaning if one consumer validates the coupon, no one else can validate it again.

Directory

An application to group multiple coupons and loyalty cards for mobile apps, websites, touch TVs, Facebook tabs. Directories can require authentication or payments in order to access the coupons inside.

Loyalty card

A loyalty card is a card where consumers can earn and redeem points/stamps in order to receive coupons. Configure the number of points/stamps for each reward (coupon) in your Coupontools dashboard.

ID overview

cam_xxxxxx Coupon ID Unique reference for a coupon
loc_xxxxxx Coupon redeem location ID Unique reference for a coupon redeem location
xxxxxx Directory ID Unique reference for a directory
xxxxxx Directory user ID Unique reference for a directory user
dir_xxxxxx Legacy directory ID Unique reference for a legacy directory
reg_xxxxxx Legacy directory user ID Unique reference for a legacy directory user
cat_xxxxxx Legacy directory category ID Unique reference for a legacy directory category
xxxxxx Wallet loyalty card ID Unique reference for a wallet-based loyalty card
xxxxxx Wallet loyalty card user ID Unique reference for a wallet-based loyalty card. Alternatively called a stat ID.
loy_xxxxxx Web loyalty card ID Unique reference for a web-based loyalty card
lus_xxxxxx Web loyalty card user ID Unique reference for a web-based loyalty card user
lloc_xxxxxx Web loyalty card redeem location ID Unique reference for a web-based loyalty card redeem location
sub_xxxxxx Subaccount ID Unique reference for a subaccount
gro_xxxxxx Smstools group ID Unique reference for a Smstools group
con_xxxxxx Smstools contact ID Unique reference for a Smstools contact

Authentication

The API client ID and secret must be sent along with each API request by providing it in the HTTP call's Authorization header. Your API credentials can be found under the "REST API" integration on the "Integrations" page in your Coupontools dashboard. Of course, it's very important to keep the API keys secure. Do not ever share them!

Request headers

X-Client-Id Login to your account to get your API keys
X-Client-Secret Login to your account to get your API keys

API of more recent products like the version 4 directories and wallet based loyalty cards use different headers to send along their API credentials.

x-api-key Login to your account to get your API keys
x-api-secret Login to your account to get your API keys

Webhooks

Use webhooks to be notified about events that happen in a Coupontools account.

Webhooks are a system of automated notifications indicating that an event has occurred in your account. Rather than requiring you to pull information via our API, webhooks push information to your destination when important events occur.

Notifications are delivered via HTTP POST to a destination endpoint on your server and are sent based on the triggers you choose. Each webhook contains a notification kind and the full Coupontools object that the notification is reporting on. This information can be used to update your system or to trigger business processes.

Configuration

To configure a webhook, you'll need to:

  1. Create a webhook destination URL on your server
  2. Create a new webhook in the Control Panel by entering your webhook destination URL and selecting at least one type of notification for the webhook to fire on
  3. Set up your server to parse incoming webhooks
  4. Test your webhook handling code

Retries

We will resend webhook notifications every hour for up to 24 hours until both of the following are true:

  • The webhook responds within 30 seconds
  • The webhook responds with a successful HTTP response code. (i.e. 2xx)