How to integrate my POS system via the API?

General overview;

Each coupon or voucher has a unique ID:

Example: https://digicpn.com/p/abcdef/abcdefghijklmn

Summary:
abcdef = campaign_id
abcdefghijklmn = session_id

The platform is able to display the unique session_id as a barcode in any format.
Read here to see all our available barcode formats.

How to develop the integration on the POS side:

1) the cashier will scan the barcode or enters the session_id manually.
In our example here the session_id, barcode value equals kkfiznr8Yp8630h82es8d

2) the pos will lookup the session_id with the API:
https://docs.coupontools.com/api/coupon#get-session

Response:

{

	"status": {
		"status": "OK"
	},
	"campaign": "cam_12345",
	"action": "retrieve_all_session_data",
	"session": "kkfiznr8Yp8630h82es8d,"
	"session_url": "https://digicpn.com/p/v6n7gn/kkfiznr8Yp8630h82es8d",
	"sequenceid": "19878460",
	"customid": "",
	"data": {
		"status": {
			"created_date_utc": "2019-03-25 10:43:50",
			"opened": "0",
			"open_date_utc": "",
			"played": "0",
			"played_date_utc": "",
			"claimed": "1",
			"claim_date_utc": "2019-03-25 10:44:05",
			"claimtype": "",
			"saved_to_passbook": "0",
			"saved_to_passbook_date_utc": "",
			"saved_to_androidpay": "0",
			"saved_to_androidpay_date_utc": "",
			"validated": "0",
			"validation_date_utc": "",
			"own_validation_code": "ding_COdHepKvqNrNC8OU",
			"validation_value": "",
			"redeem_location_ID": "",
			"voided": "0",
			"unvoided_date_utc": "2019-03-25 10:44:05",
			"locked": "0",
			"unlocked_date_utc": "",
			"value": "",
			"customid": "",
			"expiration_date": "2019-03-02 02:00:00",
			"utm_campaign": null,
			"utm_source": null,
			"utm_medium": null,
			"utm_term": null,
			"utm_content": null,
			"redeem_location_company_name": "Show",
			"redeem_location_street": "street",
			"redeem_location_zip": "",
			"redeem_location_city": "Foo",
			"redeem_location_province": "Bar",
			"redeem_location_country": "Baz",
			"redeem_location_phone": "",
			"redeem_location_website": "https://www.coupontools.com",
			"redeem_location_pincode": "aSQbSs"
		},
		"user": {
			"gender": "Male",
			"first_name": "John",
			"last_name": "Johnson",
			"address": "Wallstreet 1",
			"zip": "10000",
			"city": "New York",
			"birthday": "1970-01-01",
			"email": "info@mymailbox.com",
			"phone": "1234567890",
			"answer": "yes",
			"custom1": "A",
			"custom2": "B",
			"custom3": "C",
			"custom4": "D",
			"custom5": "E",
			"custom6": "F",
			"custom7": "G",
			"customid": "1A2B",
			"checkbox1": "1",
			"checkbox2": "0",
			"checkbox3": "1",
			"checkbox4": "0",
			"device": "Windows",
			"profile_picture": "",
			"ip_lat": "",
			"ip_long": ""
		},
		"campaign": {
			"ID": "cam_1010951",
			"code": "v6n7gn",
			"url": "https://digicpn.com/p/v6n7gn",
			"status": "test",
			"coupon_tags": ""
		}
	}
}

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

In case the coupon session was found the POS knows the status:

"validated": "0"

In case the session was already used (validated=1) the POS can give an notification in the POS "The coupon or voucher $$sessionid was already used at $$validation_date_utc"
In case the session was not used the POS knows the discount value. This can be saved in either value field or in the custom fields.

OPTIONAL STEP: temporary LOCK a coupon/voucher

With the UPDATE session endpoint the POS can set the coupon as LOCKED during check-out before validation.
https://docs.coupontools.com/api/coupon#update-session
If you use the locked step you need to verify the locked status also in the first lookup step.

FINAL STEP: validation of the coupon/voucher

With the UPDATE session endpoint the POS can mark the coupon as used by sending the "validate" command.
https://docs.coupontools.com/api/coupon#update-session

Note:
There is an optional fields to use at validation:

money_spent
Money spent (Format: 0.000)

It allows the POS to store the total money spent value at checkout for reporting in Coupontools.

Updated on: 21/02/2024