Promo codes

• /api/v2/promo codes/groups/list/- List promo codes
• /api/v2/promo codes/info/- Retrieve information about a specific promo code
• /api/v2/promo codes/activate/ - Manual promo code activation

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

Simple promo codes

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

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

• api/v2/promo codes/coupons/numbers/add - Create a certificate
• api/v2/promo codes/coupons/groups/list - List certificates
• api/v2/promo codes/coupons/numbers/status - Check certificate status
• api/v2/promo codes/coupons/groups/activate - Activate a certificate
• api/v2/promo codes/coupons/groups/use - Use a certificate
• api/v2/promo codes/coupons/numbers/delete - Delete a certificate

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.

Certificate states

During the lifetime of a certificate, it progresses 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– the name of the group to which the certificate belongs. Accounting 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/promo codes/groups/list/ - List promo codes

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.

Request Parameters

token=qx6s4gsdvsdhsdsd

store_department_id=345

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

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

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

{
    "status": "error",
    "message": "Permission denied. Provide auth token and store_department_id"
}

token=qx6s4gsdvsdhsdsd

store_department_id=345 

PROMO15

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

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

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

{
    "status": "error",
    "message": "Permission denied. Provide auth token and store_department_id"
}

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

token=qx6s4gsdvsdhsdsd

store_department_id=345 

user_phone=79001234567

group_name=PROMO50

number=xyzt_2938

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

"status":"ok"

"promo code_status": 2

{
 "status": "ok",
 "promo code_status": 2
}

{
    "status": "error",
    "message": "Permission denied. Provide auth token and store_department_id"
}

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

{
    "status": "error",
    "message": "Phone is not valid"
}

{
    "status": "error",
    "message": "Invalid value of email"
}

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

/api/v2/promo codes/coupons/numbers/add - Certificate creation

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

Preparation

Before certificate creation, a file containing numbers of certificates needs to be created. Available file formats:

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

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.

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 recommended to use numbers and/or letters.
• Uniqueness: certificate number needs to be strictly unique.

Request parameters

token=qx6s4gsdvsdhsdsd

store_department_id=345

type=2

value=5000

name=5$ Promo Certificate

target_dep_id=3487

pin_code=4455

Request body

—

Server response

"status":"ok"

"status_code": -4201

"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/promo codes/coupons/groups/list/ - List certificates

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

Request parameters

token=qx6s4gsdvsdhsdsd

store_department_id=345

Server response

"status":"ok"

"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/promo codes/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/promo codes/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

token=qx6s4gsdvsdhsdsd

store_department_id=345 

number=testcert

Server Response

"status":"ok"

"used": false

"value_type": 2

"deleted": false

"group":{
   "id":1649,
   "name":"TTTTTTTTT"
}

Request example

https://sailplay.net/api/v2/promo codes/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/promo codes/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

token=qx6s4gsdvsdhsdsd

store_department_id=345

number=testcert1

target_dep_id=3487

Server response

"status":"ok"

"activated": true

Request example

https://sailplay.net/api/v2/promo codes/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/promo codes/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

token=qx6s4gsdvsdhsdsd

store_department_id=345 

jn321jns

target_dep_id=3487

Server response

"status":"ok"

"used": true

Request example

https://sailplay.net/api/v2/promo codes/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/promo codes/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

token=qx6s4gsdvsdhsdsd

store_department_id=345 

jn321jns

Server response

"status":"ok"

"deleted": true

"deleted_date": "2017-11-30T17:17:18.071"

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