Coupon
List coupons
Retrieve a list of all coupons.
POST
https://api.coupontools.com/v3/coupon/list
Authentication:
API KeysParameters
Parameter | Input | ||
---|---|---|---|
only_active | true/false | When set to true, only campaigns marked as 'active' will be returned | Optional |
folder | Folder ID | If defined, the response will only contain coupons in the specified folder | Optional |
tags | String of coupon tags | If defined, the response will only contain coupons containing that tag | Optional |
category | Category ID (cat_XXX) | If defined, the response will only contain coupons of that category | Optional |
Example
Response
Possible errors
Get coupon
Retrieve coupon information by ID.
POST
https://api.coupontools.com/v3/coupon/info
Authentication:
API KeysParameters
Parameter | Input | ||
---|---|---|---|
campaign | Coupon ID (cam_XXXXXX) | Can be found in the list of all coupons | Required |
show_usage_stats | true/false | Defaults to false, will add the total number of custom validation codes and number of claimed custom codes | Optional |
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
Parameter | Input | ||
---|---|---|---|
campaign | Coupon ID (cam_XXXXXX) | Can be found in the list of all coupons | Required |
page | Page ID | If there are 5000 or more records these will be split in multiple pages. | Optional |
start_date | Start date of the sessions in UTC | Inclusive. Must be format 'yyyy-mm-dd hh-mm' or 'yyyy-mm-dd' | Optional |
end_date | End date of the sessions in UTC | Inclusive. Must be format 'yyyy-mm-dd hh-mm' or 'yyyy-mm-dd' | Optional |
Example
Response
Possible errors
Get coupon session
Retrieve data from single coupon session.
POST
https://api.coupontools.com/v3/couponsession/data
Authentication:
API KeysParameters
Parameter | Input | ||
---|---|---|---|
couponsession | Unique session code (example: ac6s7u3g8a25ja7x9qg87) | Can be found in the URL, webhooks, statistics or through API call | Required |
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
Parameter | Input | ||
---|---|---|---|
couponsession | Unique session code (example: ac6s7u3g8a25ja7x9qg87) | Can be found in the URL, webhooks, statistics or through API call | Required |
operation | void unvoid lock unlock claim validate unvalidate activate | 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. | Optional |
customfield1 - customfield7 | Custom field 1 through 7 | Max. 50 characters | Optional |
customid | Custom ID | Max. 50 characters (az-AZ-09) | Optional |
money_spent | Money spent | (Format: 0.000) Do not use special characters | Optional |
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
Parameter | Input | ||
---|---|---|---|
campaign | Coupon ID (cam_XXXXXX) | Can be found in the list of all coupons | Required |
startsequence | The sequence ID of the first session | Returned in multiplesingleuse/create. Only 1 of "startsequence" or "endsequence" is required | Required |
endsequence | The sequence ID of the last session | Returned in multiplesingleuse/create. Only 1 of "startsequence" or "endsequence" is required | Required |
operation | void unvoid lock unlock claim activate | 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. | Optional |
customfield1 - customfield7 | Add data to custom field 1 through 7 | Max. 50 characters | Optional |
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
Parameter | Input | ||
---|---|---|---|
campaign | Coupon ID (cam_XXXXXX) | Only required when searching in specific coupon. Can be found in the list of all coupons. | Optional |
code | Custom validation code | Minimum 5 characters | Optional |
phone | Phone number | Minimum 5 characters | Optional |
Email address | Minimum 5 characters | Optional |
Example
Response
Possible errors
Delete session
Delete a coupon session.
POST
https://api.coupontools.com/v3/singleuse/remove
Authentication:
API KeysParameters
Parameter | Input | ||
---|---|---|---|
campaign | Coupon ID (cam_XXXXXX) | Can be found in the list of all coupons | Required |
couponsession | Unique session code (example: ac6s7u3g8a25ja7x9qg87) | Can be found in the URL, webhooks, statistics or through API call | Required |
Example
Response
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
Parameter | Input | ||
---|---|---|---|
campaign | Coupon ID (cam_XXXXXX) | Can be found in the list of all coupons | Required |
firstname | First name | Optional | |
lastname | Last name | Optional | |
Optional | |||
phone | Phone | Optional | |
customid | Custom ID | Max. 50 characters (az-AZ-09) | Optional |
customfield1 - customfield7 | Custom field 1 through 7 | Max. 50 characters | Optional |
customvalcode | Custom validation code | Max. 100 characters (az-AZ-09). Cannot be combined with 'autovalcode' | Optional |
autovalcode | Automatically generates unique validation code | Available parameters: 6digits, 8digits, 10digits. Cannot be combined with 'customvalcode' | Optional |
duplicate_check | email phone customid | 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 | Optional |
utm_campaign utm_source utm_medium utm_term utm_content | Google Analytics tags | Will appear in exported statistics | Optional |
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
Parameter | Input | ||
---|---|---|---|
campaign | Coupon ID (cam_XXXXXX) | Caµn be found in the list of all coupons | Required |
amount | Amount of single-use URLs to generate | Only digits allowed | Required |
status | normal/voided/activated | Defaults to normal | Optional |
automated_codes | true/false (custom validation codes) | If true, requires the parameters below (default = false) | Optional |
code_prefix | Prefix of custom validation code | Optional | |
code_length | Length of code excluding prefix | Number between 10 and 25 inclusive | Optional |
code_type | numeric/alphanumeric | The type of the custom validation code | Optional |
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
Parameter | Input | ||
---|---|---|---|
campaign | Coupon ID (cam_XXXXXX) | Can be found in the list of all coupons | Required |
Email address receiving coupon | Required | ||
couponsession | Unique session code (example: ac6s7u3g8a25ja7x9qg87) | If not defined, we'll generate a new coupon session | Optional |
subject | Subject of email | Optional | |
firstname | Personalize email with a first name. | The email body must contain [FIRSTNAME] | Optional |
lastname | Personalize email with a last name. | The email body must contain [LASTNAME] | Optional |
check_unique | Check if email address already received coupon | When not unique, email is not send | Optional |
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
Parameter | Input | ||
---|---|---|---|
campaign | Coupon ID (cam_XXXXXX) | Can be found in the list of all coupons | Required |
phone | Phone number receiving coupon | International E.164 notation | Required |
couponsession | Unique session code (example: ac6s7u3g8a25ja7x9qg87) | If not defined, we'll generate a new coupon session | Optional |
body | SMS body text | The unique coupon URL will be added to each message | Optional |
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
Parameter | Input | ||
---|---|---|---|
campaign | Coupon ID (cam_XXXXXX) | Can be found in the list of all coupons | Required |
message | Push notification message | Required |