Coupon
List coupons
Retrieve a list of all coupons.
POST
https://api.coupontools.com/v3/coupon/list
Authentication:
API KeysParameters
When set to true, only campaigns marked as 'active' will be returned
If defined, the response will only contain coupons in the specified folder
If defined, the response will only contain coupons containing that tag. Comma separated for each new tag
If defined, the response will only contain coupons of that category
Example
Response
Possible errors
Get coupon
Retrieve coupon information by ID.
POST
https://api.coupontools.com/v3/coupon/info
Authentication:
API KeysParameters
Can be found in the list of all coupons
Defaults to false, will add the total number of custom validation codes and number of claimed custom codes
Example
Response
Possible errors
Coupon session
List coupon sessions
Retrieve a list of all sessions from a coupon.
POST
https://api.coupontools.com/v3/campaign/data
POST
https://api.coupontools.com/v3/campaign/opens
POST
https://api.coupontools.com/v3/campaign/claims
POST
https://api.coupontools.com/v3/campaign/validations
Authentication:
API KeysParameters
Can be found in the list of all coupons
Page ID. If there are 5000 or more records these will be split in multiple pages.
Start date of the sessions in UTC. Inclusive.
End date of the sessions in UTC. Inclusive.
Example
Response
Possible errors
Get coupon session
Retrieve data from single coupon session.
POST
https://api.coupontools.com/v3/couponsession/data
Authentication:
API KeysParameters
Unique session code (example: ac6s7u3g8a25ja7x9qg87). Can be found in the URL, webhooks, statistics or through API call
Example
Response
Possible errors
Update session
Update data from 1 coupon session. For example, set the session from claimed to validated status.
POST
https://api.coupontools.com/v3/couponsession/update
Authentication:
API KeysParameters
Unique session code (example: ac6s7u3g8a25ja7x9qg87). Can be found in the URL, webhooks, statistics or through API call
void: sets coupon session to voided status unvoid: unsets the voided status lock: sets coupon session to locked status unlock: unsets the locked status claim: sets coupon session to claimed status. validate: sets coupon session to validated status. unvalidate: sets coupon session to unvalidated status. activate: will unvoid and start the session, if the coupon has a flexible expiry date, the expiration time will be calculated.
Custom field 1 through 7. Max. 50 characters
Max. 50 characters (az-AZ-09)
Money spent. (Format: 0.000) Do not use special characters
Example
Response
Possible errors
Update sessions
Update data from multiple coupon sessions. For example, set the sessions from claimed to validated status. Must define at least start sequence and/or end sequence. The API will update all sessions after, before, or between start and end sequence.
POST
https://api.coupontools.com/v3/batch/update
Authentication:
API KeysParameters
Can be found in the list of all coupons
Returned in multiplesingleuse/create. Only 1 of "startsequence" or "endsequence" is required
Returned in multiplesingleuse/create. Only 1 of "startsequence" or "endsequence" is required
void: sets coupon session to voided status unvoid: unsets the voided status lock: sets coupon session to locked status unlock: unsets the locked status claim: sets coupon session to claimed status. activate: will unvoid and start the session, if the coupon has a flexible expiry date, the expiration time will be calculated.
Max. 50 characters
Example
Response
Possible errors
Search session
Search coupon session based on your custom validation code, phone number or email.
POST
https://api.coupontools.com/v3/couponsession/search
POST
https://api.coupontools.com/v3/campaignsession/search
Authentication:
API KeysParameters
Only required when searching in specific coupon. Can be found in the list of all coupons.
Custom validation code. Minimum 5 characters
Minimum 5 characters
Minimum 5 characters
Example
Response
Possible errors
Delete session
Delete a coupon session.
POST
https://api.coupontools.com/v3/singleuse/remove
Authentication:
API KeysParameters
Can be found in the list of all coupons
Unique session code (example: ac6s7u3g8a25ja7x9qg87). Can be found in the URL, webhooks, statistics or through API call
Example
Response
Possible errors
Generate session barcode
Generate a barcode for a session.
POST
https://api.coupontools.com/v3/couponsession/barcode
Authentication:
API KeysParameters
Unique session code (example: ac6s7u3g8a25ja7x9qg87). Can be found in the URL, webhooks, statistics or through API calls
Type of the barcode.
Example
Possible errors
Single-use
Create single-use URL
Create a single-use URL for a coupon. Prefill data like first name, last name, custom validation code, ...
POST
https://api.coupontools.com/v3/singleuse/create
Authentication:
API KeysParameters
Can be found in the list of all coupons
Custom ID. Max. 50 characters (az-AZ-09)
Custom field 1 through 7 Max. 50 characters
Custom validation code Max. 100 characters (az-AZ-09). Cannot be combined with 'autovalcode'
Automatically generates unique validation code. Cannot be combined with 'customvalcode'
Defaults to false. If enabled, we will verify if the same user input already received a single-use url for that coupon based on the selected field (email, phone or customid), and return the duplicated session instead of creating a new session
Google Analytics tags. Will appear in exported statistics
This expiration date is for this single use session and will override the campaign expiration date. The existing timezone from the campaign is used.
Example
Response
Possible errors
Create multiple single-use URLs
Create multiple single-use URLs for a coupon.
POST
https://api.coupontools.com/v3/multiplesingleuse/create
Authentication:
API KeysParameters
Can be found in the list of all coupons
Amount of single-use URLs to generate. Defaults to 10
Defaults to normal
If true, requires the parameters below. Defaults to false
Prefix of custom validation code
Number between 10 and 25 inclusive
The type of the custom validation code
Example
Response
Possible errors
Distribution
Send coupon by email
You need to have an email marketing platform connected to be able to send out marketing emails (check out: integrations -> email marketing).
POST
https://api.coupontools.com/v3/send/email
Authentication:
API KeysParameters
Can be found in the list of all coupons
Email address receiving coupon
Unique session code (example: ac6s7u3g8a25ja7x9qg87). If not defined, we'll generate a new coupon session
Subject of email
Personalize email with a first name. The email body must contain [FIRSTNAME]
Personalize email with a last name. The email body must contain [LASTNAME]
Check if email address already received coupon. When not unique, email is not send
Example
Response
Possible errors
Send coupon by text message
You need to have an SMS marketing platform connected to be able to send out SMS messages (check out: integrations -> SMS marketing).
E.164 phone number format:
First of all, in the international E.164 notation, a leading '0' is removed.
The UK mobile phone number '07911 123456' in international format is '+44 7911 123456', so without the leading zero.
Secondly, in the E.164 notation, all spaces, dashes ['-'] and parentheses [ '(' and ')'] are removed, besides the leading '+', all characters should be numeric.
Example: +447911123456
POST
https://api.coupontools.com/v3/send/sms
Authentication:
API KeysParameters
Can be found in the list of all coupons
Phone number receiving coupon. International E.164 notation
Unique session code (example: ac6s7u3g8a25ja7x9qg87). If not defined, we'll generate a new coupon session
SMS body text. The unique coupon URL will be added to each message
Example
Response
Possible errors
Notification
Send push notification
Send push notification to all users of a coupon. This requires the coupon to be added in the mobile wallet.
POST
https://api.coupontools.com/v3/coupon/pushnotification/list
Authentication:
API KeysParameters
Can be found in the list of all coupons
Push notification message