Coupon

List coupons

Retrieve a list of all coupons.

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

Authentication:

API Keys

Parameters

Optional 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. Comma separated for each new tag
Optional category Category ID (cat_XXX)
If defined, the response will only contain coupons of that category

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

Required campaign Coupon ID (cam_XXXXXX)
Can be found in the list of all coupons
Optional show_usage_stats true | false
Defaults to false, will add the total number of custom validation codes and number of claimed custom codes

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

Required campaign Coupon ID (cam_XXXXXX)
Can be found in the list of all coupons
Optional page Numeric
Page ID. If there are 5000 or more records these will be split in multiple pages.
Optional start_date Date (format: 'yyyy-MM-dd hh-mm' | 'yyyy-MM-dd')
Start date of the sessions in UTC. Inclusive.
Optional end_date Date (format: 'yyyy-MM-dd hh-mm' | 'yyyy-MM-dd')
End date of the sessions in UTC. Inclusive.

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

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

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

Required couponsession String
Unique session code (example: ac6s7u3g8a25ja7x9qg87). Can be found in the URL, webhooks, statistics or through API call
Optional 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 String
Custom field 1 through 7. Max. 50 characters
Optional customid Custom ID
Max. 50 characters (az-AZ-09)
Optional money_spent Decimal number
Money spent. (Format: 0.000) Do not use special characters

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

Required 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
Optional 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

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

Optional campaign Coupon ID (cam_XXXXXX)
Only required when searching in specific coupon. Can be found in the list of all coupons.
Optional code String
Custom validation code. Minimum 5 characters
Optional phone Phone number
Minimum 5 characters
Optional email Email address
Minimum 5 characters

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

Required campaign Coupon ID (cam_XXXXXX)
Can be found in the list of all coupons
Required couponsession String
Unique session code (example: ac6s7u3g8a25ja7x9qg87). Can be found in the URL, webhooks, statistics or through API call

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

Generate session barcode

Generate a barcode for a session.

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

Authentication:

API Keys

Parameters

Required couponsession String
Unique session code (example: ac6s7u3g8a25ja7x9qg87). Can be found in the URL, webhooks, statistics or through API calls
Required type code39 | code128b | pdf417 | aztec | qrcode
Type of the barcode.

Example

Loading...

Possible errors

400: Missing parameter: couponsession
400: Couponsession {couponsession} does not exist
400: Missing parameter: type
400: Unsupported type: {type}

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

Required campaign Coupon ID (cam_XXXXXX)
Can be found in the list of all coupons
Optional firstname First name
 
Optional lastname Last name
 
Optional email Email
 
Optional phone Phone
 
Optional customid String
Custom ID. Max. 50 characters (az-AZ-09)
Optional customfield1 - customfield7 String
Custom field 1 through 7 Max. 50 characters
Optional customvalcode String
Custom validation code Max. 100 characters (az-AZ-09). Cannot be combined with 'autovalcode'
Optional autovalcode 6digits | 8digits | 10digits
Automatically generates unique validation code. 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 String
Google Analytics tags. Will appear in exported statistics
Optional expiry_date Date (format: 'yyyy-MM-dd HH:mm:ss')
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

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

Required campaign Coupon ID (cam_XXXXXX)
Can be found in the list of all coupons
Optional amount Number
Amount of single-use URLs to generate. Defaults to 10
Optional status normal | voided | activated
Defaults to normal
Optional automated_codes true | false
If true, requires the parameters below. Defaults to false
Optional code_prefix String
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

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

Required campaign Coupon ID (cam_XXXXXX)
Can be found in the list of all coupons
Required email Email
Email address receiving coupon
Optional couponsession String
Unique session code (example: ac6s7u3g8a25ja7x9qg87). If not defined, we'll generate a new coupon session
Optional subject String
Subject of email
Optional firstname String
Personalize email with a first name. The email body must contain [FIRSTNAME]
Optional lastname String
Personalize email with a last name. The email body must contain [LASTNAME]
Optional check_unique true | false
Check if email address already received coupon. When not unique, email is not send

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

Required campaign Coupon ID (cam_XXXXXX)
Can be found in the list of all coupons
Required phone Phone number
Phone number receiving coupon. International E.164 notation
Optional couponsession String
Unique session code (example: ac6s7u3g8a25ja7x9qg87). If not defined, we'll generate a new coupon session
Optional body String
SMS body text. The unique coupon URL will be added to each message

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

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

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