A promo code mechanism is implemented in SailPlay. Promo codes can be used in SMS and Emails, applied to purchases, or trigger custom user scenarios. Promo codes are separated into two types - simple and activation, and business scenarios differ on the type of the promo code group.
Simple promo codes can be used in SMS, Emails, or be applied to purchases. Promo codes are uploaded to a partner's account through the SPanel interface. After the upload is complete, promo codes from the created group can be communicated to users through SMS and Email with the use of the dynamic parameter in campaigns and triggered chains. Sent promo codes can be used in a partner's existing systems, as well as passed alongside the cart during the purchase creation, based on which custom promo campaigns can be applied.
Activation promo codes can be used in SMS, Emails, or trigger custom actions utilizing the triggered chains mechanism. Promo codes are uploaded to a partner's account through the SPanel interface. After the upload is complete, promo codes from the created groups can be communicated to users through SMS and Email with use of the dynamic parameters in campaigns and triggered chains. Promo codes can be applied to a specific customer using the activation method or through the SPanel interface. After the promo code is successfully activated, the customer receives the "Applied promo code [promo code name]" tag, that can fire off the triggered chain to perform custom actions.
Certificates allow the creation of certificate groups, differentiating by shop and value and can be used to pay for the purchase or part of the purchase with the certificate. The main business scenario that certificates allow to achieve is the distribution of certificates to be used as gift cards.
During the lifetime of a certificate, it progresses through several irreversible states:
Certificate has several attributes/properties:
This API method is used for retrieval of the list of available promo code groups inside of the Department.
The method can be used, for example, to identify groups of promo codes available for customers, or to retrieve the number of unused promo codes.
Is the parameter mandatory? | Parameter name | Parameter description | Data type | Example |
yes | token | see here | see the request example |
token=qx6s4gsdvsdhsdsd |
yes | store_department_id | see here | integer |
store_department_id=345 |
https://sailplay.net/api/v2/promo codes/groups/list/?store_department_id=3620&token=12b3278xcb23b2498vxvb230nrfv24erf9
Parameter(key) | Description | Data Type | Example |
---|---|---|---|
status | request status | JSON String |
"status":"ok" |
|
|
|
"groups": { "disabled": [], "enabled": [ { "create_date": "2016-09-29T23:14:50", "reserved_count": 62, "apply_items_once": true, "receipted_count": 38, "applied_count": 0, "unused_count": 62, "id": 470, "update_date": "2016-09-29T23:14:50", "name": "$5 voucher", "total_count": 100, "group_type": 2 }, { "create_date": "2016-10-04T23:42:22", "reserved_count": 79, "apply_items_once": true, "receipted_count": 21, "applied_count": 0, "unused_count": 79, "id": 492, "update_date": "2016-10-04T23:42:22", "name": "$100 voucher", "total_count": 100, "group_type": 2 } ] } placeholderplaceholderplacehold |
{ "status": "ok", "groups": { "disabled": [], "enabled": [ { "create_date": "2016-09-29T23:14:50", "reserved_count": 62, "apply_items_once": true, "receipted_count": 38, "applied_count": 0, "unused_count": 62, "id": 470, "update_date": "2016-09-29T23:14:50", "name": "$5 voucher", "total_count": 100, "group_type": 2 }, { "create_date": "2016-10-04T23:42:22", "reserved_count": 79, "apply_items_once": true, "receipted_count": 21, "applied_count": 0, "unused_count": 79, "id": 492, "update_date": "2016-10-04T23:42:22", "name": "$100 voucher", "total_count": 100, "group_type": 2 } ] } }
This pair of store_deprtment_id and token are incorrect or missing in the system.
{ "status": "error", "message": "Permission denied. Provide auth token and store_department_id" }
The following API method is used to retrieve the description, status information, or to check the existence of a specific promo code.
The method can be used, for example, prior to the promo code activation supplied by a user, to check if it is valid, or to find out the promo code group the supplied promo code number is associated with.
Is the parameter mandatory? | Parameter name | Parameter description | Data type | Example |
yes | token | see here | see the request example |
token=qx6s4gsdvsdhsdsd |
yes | store_department_id | see here |
integer |
store_department_id=345 |
yes | number | Promo code number | string (1-128 symbols) |
PROMO15 |
https://sailplay.net/api/v2/promo codes/info/?store_department_id=3620&token=12b3278xcb23b2498vxvb230nrfv24erf9&number=yfubf_mm400
Parameter(key) | Description | Data Type | Example |
---|---|---|---|
status | request status | JSON String |
"status":"ok" |
|
|
|
"numbers": [ { "applied_times": 0, "can_be_applied": true, "group": { "apply_items_once": true, "enabled": true, "id": 498, "name": "$400 voucher" }, "number": "yfubf_mm400", "is_published": false } ] placeholderplaceholderplacehold |
{ "status": "ok", "numbers": [ { "applied_times": 0, "can_be_applied": true, "group": { "apply_items_once": true, "enabled": true, "id": 498, "name": "$400 voucher" }, "number": "yfubf_mm400", "is_published": false } ] }
This pair of store_deprtment_id and token are incorrect or missing in the system.
{ "status": "error", "message": "Permission denied. Provide auth token and store_department_id" }
Promo code with this number does not exist in partner's system.
{ "status": "error", "message": "Number not found" }
The following API method allows activation of the chosen promo code for the chosen user. This method only works with "Activation" type promo codes.
If the method is executed successfully, the user will receive an "Applied promo code [promo code group name]" tag.
Method is used, for example, when a client activates a promo code on the partner's website. Method activates a promocde (and will prevent it from being redeemed again, if the promo code is single-use), as well as launches appropriate triggered chains, if they are set up in the partner's account.
Is the parameter mandatory? | Parameter | Parameter description | Data type | Example |
yes | token | see here |
see the request example |
token=qx6s4gsdvsdhsdsd |
yes | store_department_id | see here |
integer |
store_department_id=345 |
yes |
user_phone, email or origin_user_id |
Client identifier. For more information look here. |
string |
user_phone=79001234567 |
yes | group_name | Promo code group name | string (1-128 symbols) |
group_name=PROMO50 |
yes | number | Promo code number to be activated | string (1-128 symbols) |
number=xyzt_2938 |
https://sailplay.net/api/v2/promo codes/activate?&store_department_id=111&token=da32f321d2516c8e56142f2430bea4f72a80a6ae&phone=79000000000&group_name=PROMO25&number=NJ23Z
Parameter(key) | Description | Data type | Example |
---|---|---|---|
status | request status | JSON String |
"status":"ok" |
promo code_status |
Status of a specific promo code. Can return the following values: 1 - the code is available for distribution, 2 - the code was sent to a user (user was notified about the promo code's existance), 3 - the code is used in at least one promo campaign applied to a purchase |
JSON Number |
"promo code_status": 2 placeholderplaceholderplacehold |
{
"status": "ok",
"promo code_status": 2
}
This pair of store_deprtment_id and token are incorrect or missing in the system.
{ "status": "error", "message": "Permission denied. Provide auth token and store_department_id" }
Promo code with this number is not found in the partner's system.
{ "status": "error", "message": "Number not found" }
Incorrect phone format.
{ "status": "error", "message": "Phone is not valid" }
Incorrect E-mail format
{ "status": "error", "message": "Invalid value of email" }
The user is not found in partner's system
{ "status": "error", "message": "User not found" }
Method is used to create new certificate groups in the system. HTTP-method: POST
Before certificate creation, a file containing numbers of certificates needs to be created. Available file formats:
When using .txt and .csv formats, certificate numbers should be separated by a new line. When using .xls and .xlsx formats, numbers should be specified in a single column where one cell contains a single certificate number.
Is the parameter mandatory? | Parameter | Parameter description | Data type | Example |
yes | token | see here | see request example |
token=qx6s4gsdvsdhsdsd |
yes | store_department_id | see here | integer |
store_department_id=345 |
yes | type | System parameter of SailPlay. Should always be set to 2 | integer |
type=2 |
yes | value | Certificate value | integer |
value=5000 |
yes | name | Certificate group name | string |
name=5$ Promo Certificate |
yes | target_dep_id | Department, to which the certificates belong | integer |
target_dep_id=3487 |
yes | pin_code | Application pin code | integer |
pin_code=4455 |
Is the parameter mandatory | Parameter | Parameter description | Data type | Example |
yes | file | file with certificate numbers | File |
— |
Parameter | Parameter description | Data type | Example |
status |
Request status: ok - if the request is successful, error - if there is an error. |
JSON String |
"status":"ok" |
status_code | Numerical status identifier. Parameter appears only in case of an error in the request. | JSON Number |
"status_code": -4201 |
message | Contains error message if it arises | JSON String |
"message": "Invalid file" |
{ "status":"ok" }
This pair of store_deprtment_id and token are incorrect or missing in the system.
{ "status": "error", "message": "Permission denied. Provide auth token and store_department_id" }
File format not supported or missing.
{ "status": "error", "status_code": -4201, "message": "Invalid file" }
Mandatory request parameter was not specified
{ "status": "error", "status_code": -1000, "message": "Provide required {'field': 'name'}" }
The method is used to retrieve the list of available certificate groups for the department.
Is the parameter mandatory? | Parameter name | Parameter description | Data type | Example |
yes | token | see here | see the request example |
token=qx6s4gsdvsdhsdsd |
yes | store_department_id | see here | integer |
store_department_id=345
|
Parameter | Parameter description | Data type | Example |
status |
Request status: ok - if the request is successful, error - if there is an error. |
JSON String |
"status":"ok" |
|
|
|
"groups":[ { "create_date":"2017-11-30T14:37:42.853", "name":"TTTTTTTTT", "total_count":6, "used_count":0, "activated_count":0, "id":1649 } |
https://sailplay.net/api/v2/promo codes/coupons/groups/list/?store_department_id=3620&token=12b3278xcb23b2498vxvb230nrfv24erf9
{ "status": "ok", "groups": [ { "create_date": "2016-12-15T20:36:23", "name": "Test Certificate", "total_count": 1, "used_count": 0, "activated_count": 0, "id": 924 } ] }
This pair of store_deprtment_id and token are incorrect or missing in the system.
{ "status": "error", "message": "Permission denied. Provide auth token and store_department_id" }
Method is used to retrieve information about status of a specific certificate, e.g., to check if the certificate provided by a customer is valid.
Is the parameter mandatory? | Parameter name | Parameter description | Data type | Example |
yes | token | see here | see the request example |
token=qx6s4gsdvsdhsdsd |
yes | store_department_id | see here |
integer |
store_department_id=345 |
yes | number | Certificate number | string (1-128 symbols) |
number=testcert
|
Parameter | Parameter description | Data type | Example |
status |
Request status: ok - if the request is successful, error - if there is an error. |
JSON String |
"status":"ok" |
used | Field, specifying if the certificate was already used. | JSON Boolean |
"used": false |
value_type | System parameter of SailPlay. Always set to 2. | JSON Number |
"value_type": 2 |
deleted |
Field, specifying is the certificate was deleted. |
JSON Boolean |
"deleted": false |
|
|
|
"group":{ "id":1649, "name":"TTTTTTTTT" } |
https://sailplay.net/api/v2/promo codes/coupons/numbers/status/?store_department_id=3620&token=12b3278xcb23b2498vxvb230nrfv24erf9&number=8m8iv
{ "status": "ok", "used": false, "value_type": 2, "deleted": false, "group": { "id": 1132, "name": "Test Certificate 2" }, "dep_id": 3516, "activated": false, "number": "8m8iv", "value": "50" }
This pair of store_deprtment_id and token are incorrect or missing in the system.
{ "status": "error", "message": "Permission denied. Provide auth token and store_department_id" }
Mandatory request parameter was not specified
{ "status": "error", "status_code": -1000, "message": "Provide required {'field': 'number'}" }
This method is used to activate a certificate. It should be called when a certificate is given to a customer who has redeemed it and is a mechanism of fraud protection. Thus, if, for example, a certificate number list is exposed, leaked certificates will not be valid for use, because they weren't yet activated.
Is the parameter mandatory? | Parameter? | Parameter description | Data type | Example |
yes | token | see here |
see the request example |
token=qx6s4gsdvsdhsdsd |
yes | store_department_id | see here |
integer |
store_department_id=345 |
yes | number | Certificate number | string |
number=testcert1 |
yes | target_dep_id | Department to which the certificate belongs to | integer |
target_dep_id=3487 |
Parameter | Parameter description | Data type | Example |
status |
Request status: ok - if the request is successful, error - if there is an error |
JSON String |
"status":"ok" |
activated | Field, specifying if the parameter was activated in case the request was successful | JSON Boolean |
"activated": true |
https://sailplay.net/api/v2/promo codes/coupons/numbers/activate/?store_department_id=3620&token=12b3278xcb23b2498vxvb230nrfv24erf9&number=8m8iv
{ "status": "ok", "activated": true }
This pair of store_deprtment_id and token are incorrect or missing in the system.
{ "status": "error", "message": "Permission denied. Provide auth token and store_department_id" }
Mandatory parameter was not specified
{ "status": "error", "status_code": -1000, "message": "Provide required {'field': 'number'}" }
Method is utilizes to use a specific certificate.
Important note: certificate needs to be activated before it is used. Certificate can be used only once to use the certificate value as a discount.
Is the parameter mandatory? | Parameter | Parameter description | Data type | Example |
yes | token | see here |
see the request example |
token=qx6s4gsdvsdhsdsd |
yes | store_department_id | see here |
integer |
store_department_id=345 |
yes | number | Certificate number | string |
jn321jns |
yes | target_dep_id | Department to which the certificate belongs | Integer |
target_dep_id=3487 |
Parameter | Parameter description | Date type | Example |
status |
Request status: ok - if the request is successful, error - if there is an error |
JSON String |
"status":"ok" |
used | Field, specifying if the parameter was used in case the request was successful | JSON Boolean |
"used": true |
https://sailplay.net/api/v2/promo codes/coupons/numbers/use/?store_department_id=3620&token=12b3278xcb23b2498vxvb230nrfv24erf9&number=8m8iv
{ "status": "ok", "used": true }
This pair of store_deprtment_id and token are incorrect or missing in the system.
{ "status": "error", "message": "Permission denied. Provide auth token and store_department_id" }
Mandatory parameter was not passed through
{ "status": "error", "status_code": -1000, "message": "Provide required {'field': 'number'}" }
Method is used to delete particular certificate numbers. It is possible to delete a certificate with any status.
Is the parameter mandatory? | Parameter | Parameter description | Data type | Example |
yes | token | see here |
see the request example |
token=qx6s4gsdvsdhsdsd |
yes | store_department_id | see here |
integer |
store_department_id=345 |
yes | number | Certificate number | string |
jn321jns |
Parameter | Parameter description | Data type | Example |
status |
Request status: ok - if the request is successful, error - if there is an error |
JSON String |
"status":"ok" |
deleted | Field, specifying if the parameter was used in case the request was successful | JSON Boolean |
"deleted": true |
deleted_date | Date of deletion | JSON String |
"deleted_date": "2017-11-30T17:17:18.071" |
number | Certificate number | JSON String |
"number": "testcert1" |
{ "deleted": true, "status": "ok", "deleted_date": "2017-11-30T17:17:18.071", "number": "йцв765йц7в65" }
This pair of store_deprtment_id and token are incorrect or missing in the system.
{ "status": "error", "message": "Permission denied. Provide auth token and store_department_id" }
Mandatory parameter was not passed through
{ "status": "error", "status_code": -1000, "message": "Provide required {'field': 'name'}" }