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_123456 Coupon ID Unique reference for a coupon
loc_123456 Coupon redeem location ID Unique reference for a coupon redeem location
dir_123456 Directory ID Unique reference for a directory
reg_123456 Directory user ID Unique reference for a directory user
cat_123456 Category ID Unique reference for a directory category
loy_123456 Loyalty card ID Unique reference for a loyalty card
lus_123456 Loyalty card user ID Unique reference for a loyalty card user
lloc_123456 Loyalty card redeem location ID Unique reference for a loyalty card redeem location
sub_123456 Subaccount ID Unique reference for a subaccount
gro_123456 Smstools group ID Unique reference for a Smstools group
con_123456 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 (recommended) or adding the client_id and client_secret parameters to the POST values. 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 (recommended)

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

Body parameters

client_id Login to your account to get your API keys
client_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)