Coupon

List coupons

Retrieve a list of all coupons.

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

Authentication:

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

Response

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

Response

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

Response

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

Response

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

Response

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

Response

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

Response

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

Response

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

Response

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

Response

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

Response

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

Response

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

Response

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