Promocodes

A promocode mechanism is implemented in SailPlay. Promocodes can be used in SMS and Emails, applied to purchases, or trigger custom user scenarios. Promocodes are separated into two types - simple and activation, and business scenarios differ on the type of the promocode group.

Simple promocodes

 

Simple promocodes

 

Simple promocodes can be used in SMS, Emails, or be applied to purchases. Promocodes are uploaded to a partner's account through the SPanel interface. After the upload is complete, promocodes 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 promocodes can be used in a partners's existing systems, as well as passed alongside the cart during the purchase creation, based on which custom promo campaigns can be applied.

Activation promocodes

Activation promocodes can be used in SMS, Emails, or trigger custom actions utilizing the triggered chains mechanism. Promocodes are uploaded to a partner's account through the SPanel interface. After the upload is complete, promocodes from the created groups can be communicated to users through SMS and Email with use of the dynamic parameters in campaigns and triggered chains. Promocodes can be applied to a specific customer using the activation method or through the SPanel interface. After the promocode is successfully activated, the customer receives the "Applied promo code [promocode name]" tag, that can fire off the triggered chain to perform custom actions.

Certificates

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. Main business scenario that certificates allow to achieve is distribution of certificates to be used as gift cards.

Certificate states

During the lifetime of a certificate, it progrresses through several irreversible states:

  • Created certificate. Certificate state that indicates that it exists. Certificate in this state cannot be used as a payment method.
  • Activated certificate. This state indicates that a certificate was sold and can be used as a payment method in a purchase.
  • Used certificate. Final state of a certificate, indicating that it was used in a purchase as a payment method.

Certificate attributes

Certificate has several attributes/properties:

  • Activation – if the certificate was activated.
  • Usage – if the certificate was used inside of a purchase.
  • Group– name of the group to which the certificate belongs. Acconting for the fact that a single upload can contain a lot of certificates, even if a single certificate was created it will belong to a specific group.
  • Department – department, to which the certificate belongs to. It is mandatory to specify this department. Certificate logic requires certificates to be used inside of specific departments. Because of this, activation and usage of certificates is available only in the department the certificate was created at.
  • Value – monetary value of a certificate. E.g. a certificate's value is equal to $10, it can be used to pay for the purchase of less than $10 price.

/api/v2/promocodes/groups/list/ - List promocodes

This API method is used for retrieval of the list of available promocode groups inside of the Department.

The method can be used, for example, to identify groups of promocodes available for customers, or to retrieve the amount of unused promocodes.

Request Parameters

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

Request example

https://sailplay.net/api/v2/promocodes/groups/list/?store_department_id=3620&token=12b3278xcb23b2498vxvb230nrfv24erf9

Server response

Parameter(key)DescriptionData TypeExample
status request status JSON String
"status":"ok"
  • groups
    • disabled
    • enabled
      • create_date
      • reserved_count
      • apply_items_once
      • receipted_count
      • applied_count
      • unused_count
      • id
      • update_date
      • name
      • total_count
      • group_type
  • Promocode groups object, includes the following data:
    • Array containing objects of groups disabled at this moment. See the structure of the group object below.
    • Array, containing objects of groups that are enabled at this moment. Contains the following:
      • creation date for this promocoode group
      • amount of promocodes of this group that can be redeemed
      • uniqueness of the promocodes inside of this group
      • amount of promocodes from this group that were receipted by customers.
      • amount of promocodes in this group that was applied to a purchase
      • amount of unused promocodes in this group
      • id of the group in the partner system
      • update date of the promocode group
      • name of this promocode group
      • total amount of promocodes that were initially created in this group
      • promocode group type. Equals to "1" for simple promocodes and "2" for activation promocodes.
  • JSON Object
    • JSON Array
      • JSON Object
        • JSON String
        • JSON Number
        • JSON Boolean
        • JSON Number
        • JSON Number
        • JSON Number
        • JSON Number
        • JSON String
        • JSON String
        • JSON Number
        • JSON Number
    • JSON Array
      • JSON Object
        • JSON String
        • JSON Number
        • JSON Boolean
        • JSON Number
        • JSON Number
        • JSON Number
        • JSON Number
        • JSON String
        • JSON String
        • JSON Number
        • JSON Number
	"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

Server response example

{
	  "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
	  }
	  ]
	  }
}	 

Possible errors

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"
}

 

/api/v2/promocodes/info/ - Retrieve information about a specific promocode

The following API method is used to retrieve the description, status information, or to check existence of a specific promocode.

The method can be used, for example, prior to the promocode activation supplied by a user, to check if it is valid, or to find out the promocode group the supplied promocode number is associated with.

Request parameters

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 Promocode number string (1-128 symbols)
PROMO15

Request example

https://sailplay.net/api/v2/promocodes/info/?store_department_id=3620&token=12b3278xcb23b2498vxvb230nrfv24erf9&number=yfubf_mm400

Server response

Parameter(key)DescriptionData TypeExample
status request status JSON String
"status":"ok"
  • numbers
    • applied_times
    • can_be_applied
    • group
      • apply_items_once
      • enabled
      • id
      • name
    • number
    • is_published
  • Array that contains promo code objects, found by the specified number for the specified partner. A promocode object contains:
    • Amount of times the promocode was applied to the purchase.
    • Flag, specifying if the promocode can be applied to the purchase at this moment
    • This promocode's promocode group object. A promocode group object contains:
      • uniqueness of the promocodes inside of this group
      • flag, identifying if the group is enabled at this moment
      • group id in partner's system
      • promocode group name
    • Number of this promocode
    • Flag, if the chosen promocode was given out to a customer
  • JSON Array
    • JSON Object
      • JSON Number
      • JSON Boolean
      • JSON Object
        • JSON Boolean
        • JSON Boolean
        • JSON Number
        • JSON String
      • JSON String
      • JSON Boolean
"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

Response example

{
	  "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
	  }
	  ]
}

Possible errors

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"
}

Promocode with this number does not exist in partner's system.

{
    "status": "error",
    "message": "Number not found"
}

/api/v2/promocodes/activate/ - Promocode activation

The following API method allows activation of the chosen promocode for the chosen user. This method only works with "Activation" type promocodes.

If the method is executed successfully, the user will recieve an "Applied promo code [promocode group name]" tag.

Method is used, for example, when a client activates a promocode on the partner's website. Method activates a promocde (and will prevent it from being redeemed again, if the promocode is single-use) as well as launches appropriate triggered chains, if they are set up in the partner's account.

Request parameters

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 identifyer. For more information look here.

string

user_phone=79001234567
yes group_name Promocode group name string (1-128 symbols)
group_name=PROMO50
yes number Promocode number to be activated string (1-128 symbols)
number=xyzt_2938

Request example

https://sailplay.net/api/v2/promocodes/activate?&store_department_id=111&token=da32f321d2516c8e56142f2430bea4f72a80a6ae&phone=79251276676&group_name=PROMO25&number=NJ23Z

Server response

Parameter(key)DescriptionData typeExample
status request status JSON String
"status":"ok"

promocode_status

Status of a specific promocode. Can return the following values: 1 - code is available for distribution, 2 - code was sent to a user (user was notified about the promocode's existance), 3 - code is used in at least one promo campaign applied to a purchase

JSON Number

"promocode_status": 2

placeholderplaceholderplacehold

Response example

{
"status": "ok",
"promocode_status": 2
}

Possible errors

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"
}

Promocode 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"
}

User is not found in partner's system

{
    "status": "error",
    "message": "User not found"
}

/api/v2/promocodes/coupons/numbers/add - Certificate creation

Method is used to create new certificate groups in the system. HTTP-method: POST

Preparation

Before certificate creation, file containingnumbers of certificates needs to be created. Available file formats:

  • .txt
  • .csv
  • .xls
  • .xlsx

When using .txt and .csv formats, certificate numbers should be separated with 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.

Certificate format

  • Type: string
  • Length restriction: from 2 to 255 symbols
  • Encoding: UTF-8
  • Accepted symbols: letters from unicode compatible alphabets, numbers, special symbols. It is reccomended to use numbers and/or letters.
  • Uniqueness: certificate number needs to be strictly unique.

Request parameters

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

Request body

Is the parameter mandatory Parameter Parameter description Data type Example
yes file file with certificate numbers File

Server response

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"

Server response example

{
"status":"ok"
}

Possible errors

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'}"
}

/api/v2/promocodes/coupons/groups/list/ - List certificates

The method is used to retrieve the list of available certificate groups for the department.

Request parameters


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

 

Server response

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
    • name
    • total_count
    • used_count
    • activated_count
    • id
  • Array, containing the following information about every certificate group:
    • group creation date
    • group name
    • amount of certificates in a group
    • amount of used certificates in a group
    • amount of activated certificates in a group
    • internal group identifier
  • JSON Array
    • JSON String
    • JSON String
    • JSON Number
    • JSON Number
    • JSON Number
    • JSON Number
"groups":[
   {
      "create_date":"2017-11-30T14:37:42.853",
      "name":"TTTTTTTTT",
      "total_count":6,
      "used_count":0,
      "activated_count":0,
      "id":1649
   }

Request example

https://sailplay.net/api/v2/promocodes/coupons/groups/list/?store_department_id=3620&token=12b3278xcb23b2498vxvb230nrfv24erf9

Server response example

{
	  "status": "ok",
	  "groups": [
	  {
	  "create_date": "2016-12-15T20:36:23",
	  "name": "Test Certificate",
	  "total_count": 1,
	  "used_count": 0,
	  "activated_count": 0,
	  "id": 924
	  }
	  ]
}

Possible errors

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"
}

/api/v2/promocodes/coupons/numbers/status/ - Retrieve certificate status

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.

Request parameters

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

 

Server Response

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
    • name
  • Object, contatining information about the group certificate belongs to:
    • internal group identifier
    • group name
  • JSON Object
    • JSON Number
    • JSON String
"group":{
   "id":1649,
   "name":"TTTTTTTTT"
}

Request example

https://sailplay.net/api/v2/promocodes/coupons/numbers/status/?store_department_id=3620&token=12b3278xcb23b2498vxvb230nrfv24erf9&number=8m8iv

Server response example

{
	  "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"
}

Possible errors

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'}"
}

/api/v2/promocodes/coupons/numbers/activate/ - Certificate activation

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.

Request parameters

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

Server response

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

Request example

https://sailplay.net/api/v2/promocodes/coupons/numbers/activate/?store_department_id=3620&token=12b3278xcb23b2498vxvb230nrfv24erf9&number=8m8iv

Request response example

{
  "status": "ok",
  "activated": true
}

Possible errors

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'}"
}

/api/v2/promocodes/coupons/numbers/use/ - Use the certificate

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.

Request parameters

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 Deparment to which the certificate belongs Integer
target_dep_id=3487

Server response

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

Request example

https://sailplay.net/api/v2/promocodes/coupons/numbers/use/?store_department_id=3620&token=12b3278xcb23b2498vxvb230nrfv24erf9&number=8m8iv

Server response example

{
  "status": "ok",
  "used": true
}

Possible errors

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'}"
}

/api/v2/promocodes/coupons/numbers/delete - Delete the certificate

Method is used to delete particular certificate numbers. It is possible to delete a certificate with any status.

Request parameters

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

Server response

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"

Server respose example

{
    "deleted": true,
    "status": "ok",
    "deleted_date": "2017-11-30T17:17:18.071",
    "number": "йцв765йц7в65"
}

Possible errors

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'}"
}