Coupon

List coupons

Retrieve a list of all coupons.

POST https://api.coupontools.com/v3/coupon/list

Authentication:

API Keys

Parameters

Parameter Input Description
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

Loading...

Response

Loading...

Possible errors

515: Folder not found

Get coupon

Retrieve coupon information by ID.

POST https://api.coupontools.com/v3/coupon/info

Authentication:

API Keys

Parameters

Parameter Input Description
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

Loading...

Response

Loading...

Possible errors

200: Missing parameter: campaign
301: Invalid character in parameter: campaign
502: Campaign ID not found

Coupon session

List coupon sessions

Retrieve a list of all sessions from a coupon.

POST https://api.coupontools.com/v3/campaign/data
Only sessions that are opened
POST https://api.coupontools.com/v3/campaign/opens
Only sessions that are claimed
POST https://api.coupontools.com/v3/campaign/claims
Only sessions that are validated
POST https://api.coupontools.com/v3/campaign/validations

Authentication:

API Keys

Parameters

Parameter Input Description
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

Loading...

Response

Loading...

Possible errors

200: Missing parameter: campaign
301: Invalid character in parameter: campaign
301: Invalid character in parameter: page
303: Parameter end_date is not a valid date
303: Parameter end_date must be in the following format: yyyy-mm-dd hh:mm or yyyy-mm-dd
303: Parameter start_date is not a valid date
303: Parameter start_date must be in the following format: yyyy-mm-dd hh:mm or yyyy-mm-dd
502: Campaign ID not found

Get coupon session

Retrieve data from single coupon session.

POST https://api.coupontools.com/v3/couponsession/data

Authentication:

API Keys

Parameters

Parameter Input Description
couponsession Unique session code (example: ac6s7u3g8a25ja7x9qg87) Can be found in the URL, webhooks, statistics or through API call Required

Example

Loading...

Response

Loading...

Possible errors

200: Missing parameter: couponsession
300: Invalid character in parameter: couponsession
513: Coupon session not found

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 Keys

Parameters

Parameter Input Description
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

Loading...

Response

Loading...

Possible errors

200: Missing parameter: couponsession
300: Invalid character in parameter: couponsession
300: Invalid character in parameter: customid
302: Invalid value in parameter: operation
351: Session or coupon has expired
352: Session already was claimed before
352: Session could not be locked because it is not claimed
353: Session was already unvalidated
354: This coupon is locked
354: Session already was locked before
355: Session could not be locked because it is voided
355: Session could not be unlocked because it is voided
355: Session was already voided
355: This coupon is voided
356: Session was already unlocked
357: Session wasn't voided
358: This session was already validated
358: Session could not be locked because it is already validated
512: Coupon session not found

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 Keys

Parameters

Parameter Input Description
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

Loading...

Response

Loading...

Possible errors

200: no operation or data provided
200: startsequence or endsequence not provided
301: start/endsequence must be numeric
302: status invalid, valid statuses are: X
351: Some session(s) are expired
352: Some session(s) were already claimed
354: Some session(s) were already locked
355: Some session(s) could not be claimed because they're voided
355: Some session(s) were already voided
356: Some session(s) weren't locked
357: Some session(s) weren't voided
358: Some session(s) were already validated
359: Some session(s) weren't claimed
360: Startdate not reached
502: Provided start and end are not of the provided campaign
502: Provided start and end are not of the same campaign
513: End ID comes before start ID
513: End ID not found
513: End ID not found or not part of the campaign
513: Start ID not found
513: Start ID not found or not part of the campaign

Search session

Search coupon session based on your custom validation code, phone number or email.

POST https://api.coupontools.com/v3/couponsession/search
Search in specific coupon
POST https://api.coupontools.com/v3/campaignsession/search

Authentication:

API Keys

Parameters

Parameter Input Description
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 Email address Minimum 5 characters Optional

Example

Loading...

Response

Loading...

Possible errors

200: No filter defined
200: No parameter campaign
300: Search field 'code' must be at least 5 characters
300: Search field 'email' must be at least 5 characters
300: Search field 'phone' must be at least 5 characters
502: campaign not found
512: No results found

Delete session

Delete a coupon session.

POST https://api.coupontools.com/v3/singleuse/remove

Authentication:

API Keys

Parameters

Parameter Input Description
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

Loading...

Response

Loading...

Possible errors

200: Missing parameter: campaign
301: Invalid character in parameter: campaign
502: Campaign ID not found
513: Coupon session not found

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 Keys

Parameters

Parameter Input Description
campaign Coupon ID (cam_XXXXXX) Can be found in the list of all coupons Required
firstname First name Optional
lastname Last name Optional
email Email 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

Loading...

Response

Loading...

Possible errors

200: Missing parameter: campaign
301: Invalid character in parameter: campaign
502: Campaign ID not found

Create multiple single-use URLs

Create multiple single-use URLs for a coupon.

POST https://api.coupontools.com/v3/multiplesingleuse/create

Authentication:

API Keys

Parameters

Parameter Input Description
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

Loading...

Response

Loading...

Possible errors

200: Missing parameter: campaign
301: Invalid character in parameter: amount
301: code length must be between 3 and 30 inclusive
301: Invalid character in parameter: campaign
302: code_type must be "numeric" or "alphanumeric"
302: Parameter "status" has invalid value. Possible values are "normal", "voided" and "active"
502: Campaign ID not found
601: low on unique generated validation codes

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 Keys

Parameters

Parameter Input Description
campaign Coupon ID (cam_XXXXXX) Can be found in the list of all coupons Required
email 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

Loading...

Response

Loading...

Possible errors

104: No Email integration has been setup in your Coupontools account. Go to 'integrations' and 'Email marketing' to setup an Email provider
200: Missing parameter: campaign
301: Invalid character in parameter: campaign
305: Email address is not valid
502: Campaign ID not found
604: Email not sent to 'john@doe.com'. Reason: X

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 Keys

Parameters

Parameter Input Description
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

Loading...

Response

Loading...

Possible errors

103: No SMS integration has been setup in your Coupontools account. Go to 'integrations' and 'SMS marketing' to setup an SMS provider
200: Missing parameter: campaign
301: Invalid character in parameter: campaign
301: Phone number not valid
502: Campaign ID not found
513: Statcode not found
602: SMS not sent to 'X'. Reason: Y
605: SMS not sent to 'X'. Reason: This number is on the blacklist or opt-out list.

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 Keys

Parameters

Parameter Input Description
campaign Coupon ID (cam_XXXXXX) Can be found in the list of all coupons Required
message Push notification message Required

Example

Loading...

Response

Loading...

Possible errors

200: Missing parameter: campaign
200: Missing parameter: message
301: Invalid character in parameter: campaign
505: Campaign ID not found
507: Error sending push notification
507: 0 users have saved the campaign