Methods

• /api/v2/marketing-actions/calc/ — price calculation (based on the promo campaign rules to be applied to prices and/or bonus points in accordance with the given set of parameters: date, the point of sale, audience, cart items, etc.)

• /api/v2/marketing-actions/balance/ — information about the limits left per user (how many times this modification can further take place, how much money allocated for discounts is left, etc.)

/api/v2/marketing-actions/calc/ - price calculation

This method calculates the results of all modifications to be applied to the original product price and returns in its response data that includes but not limited to the following (per cart item):

• marketing actions applied,
• modified prices (that consider all discounts and markups to the original price if there were any),
• bonus points to be credited,
• etc

Parameters to be passed to this method include JSON object with data such as the id, quantities and original prices оf products (see detailed description below).

Request URL structure

token=qx6s4gsdvsdhsdsd

store_department_id=345 

{"1":{"sku":"item1","price":1000,"quantity":1,"discount_points":0,"min_price":250}} 

["summer2017"]

["290000000236543"]

1

Notice

• If bonus points amount is passed for a cart item (see discount_points parameter) make sure the promo campaign with the rule for using bonus points as a payment method is be created in SailPlay panel. This is a prerequisite for getting a correct new price in response (discounted by the amount of bonus points used as a payment).
• Value to be passed to discount_points parameter should be calculated on side of a web-store system / POS in accordance with business logic needed. Same goes in respect to the min_price parameter. min_price can be represented by an accounted cost of the product or any other price threshold, selling a product below which would be income-wise unreasonable.
• If the number of bonus points by which the original price need to be reduced along with other applied discounts exceeds the sum restricted by min_price the error with the number of conflicting item will be returned:

{
    "status": "error",
    "status_code": -7042,
    "message": "Max discount. Position num = 1"
 }

Request URL example

https://sailplay.com/api/v2/marketing-actions/calc/?token=qwuwq6e5546qwe6qrwe&store_department_id=456&cart={1:{"sku":"123123","price":1500,"quantity":2,"discount_points":0,"min_price":300}}&user_phone=12025550138&card_numbers=["200000000981"]&promocodes=["summer2017"]&verbose=1

Response structure

Successful response results in returning by the server a JSON-object of following structure:

"status":"ok"

"marketing_actions_applied":[
   {
      "client_msg":null,
      "service_msg":null,
      "name":"Bonus",
      "alias":"60 pre"
   }
]

"cart":{
   "total_price":"810.00",
   "total_discount_points_max":0,
   "total_points":0,
   "positions":[
      {
         "category":{
            "sku":"001105",
            "id":111540,
            "name":"Default cat"
         },
         "product":{
            "sku":"57681645",
            "id":14042,
            "name":"Item1"
         },
         "discount_points_max":0,
         "reverse_points_rate":[

         ],
         "price":"900.00",
         "new_price":"810.00",
         "min_price":"120.00",
         "num":1,
         "marketing_actions":[
            "Action 1"
         ],
         "quantity":"1",
         "points_rate":"0.0000",
         "discount_points":0,
         "points":"0.00"
      }
   ],
   "positions_count":1,
   "id":206410452
}

Response example

{
    "status": "ok",
    "marketing_actions_applied": [
        {
            "client_msg": null,
            "service_msg": null,
            "name": "Bonus",
            "alias": "60 pre"
        }
    ],
    "possible_marketing_actions": [
        {

            "client_msg": null,
            "service_msg": null,
            "name": "Bonus",
            "alias": "60 pre"
        }
    ],
    "cart": {
                "total_price": "890.00",
                "total_discount_points_max": 450,
                "total_points": 0,
                "positions": [
                    {
                        "category": {
                            "sku": "Default cat",
                            "id": 85548,
                            "name": "Default cat"
                        },
                        "product": {
                            "sku": "item_1_test",
                            "id": 3855267,
                            "name": "Item 1"
                        },
                        "discount_points_max": 450,
                        "reverse_points_rate": [],
                        "price": "900.00",
                        "new_price": "890.00",
                        "min_price": "400.00",
                        "num": 1,
                        "marketing_actions": [],
                        "quantity": "1",
                        "points_rate": "0.0000",
                        "discount_points": 10,
                        "points": 0
                    }
                ],
                "positions_count": 1,
                "id": 202558532
            }
    }

Possible error responses

store_deprtment_id and/or token are incorrect or missing

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

Invalid JSON structure in cart parameter

{
    "status": "error",
    "status_code": -1211,
    "message": "Must be valid json string {'field': 'cart'}"
}

Amount to be discounted from item’s initial price exceeds possible value.

{
    "status": "error",
    "status_code": -7042,
    "message": "Max discount. Position num = 1"
 }

Undefined error (if you encountered one please report us about it via support@sailplay.com and provide your request URL)

{
    "status": "error",
    "message": "server error"
}

Example of extended data of marketing_actions_applied (returned when verbose = 1):

"marketing_actions_applied":[
        {
            "count":null,
            "total_quantity_applied":null,
            "service_msg":"6fcc3ebd-b57c-11e7-a265-000c29bf15f9",
            "name":"Special price 546",
            "alias":"6fcc3ebd-b57c-11e7-a265-000c29bf15f9",
            "client_msg":"6fcc3ebd-b57c-11e7-a265-000c29bf15f9",
            "till_date":null,
            "total_discount":null
        }
    ]   

Additional string-value pairs contain values that are different from NULL only provided that respective restrictions were applied in promo campaign settings in SailPlay admin panel (such as "Number of times promo campaign can be applied" or "Limits per customer").

Additional string-value pairs description:

"count":1

"total_quantity_applied":"10"

"till_date":"2017-11-19T19:44:58.489"

"total_discount":"207894.00"

/api/v2/marketing-actions/balance - limits per user for a given promo campaign

The method can be used for querying limits that are retained for a particular user within a given promo campaign (how many times this price modification can further take place, how much money allocated for discounts left, etc.)

Limits that can be set within SailPlay promo campaign settings allow specifying how many times the campaign can take place and the amount of money to be discounted within it.

There are two major types of limits:

1. Per promo campaign
2. Per customer

1) Per promo campaign. For instance, if the budget of the campaign is limited, you can set the campaign to go off not more than X times in total irrespective of the number of customers who take part in it.

2) Per customer. Campaign can be set to go off not more than X times per customer who participates. Number of discounted items in the purchase can also be set. Moreover, these conditions can even more specifically defined the number of times the campaign can be applied within a calendar certain period.

Another example of this per-customer-limit is when the total amount of money to be discounted per customer is capped at some value.

In addition, a campaign can take into account minimal possible price for purchase item. Once this attribute is passed to marketing-action or purchase methods as cart item object, new price returned for an item by those methods cannot go below the attribute value. This gives more control over profit margin.

Request parameters are described below.

token=dqgfsd66asdhgds87ssd

user_phone=12025550138

store_department_id=345

Request URL example

https://sailplay.com/api/v2/marketing-actions/balance/?token=xxxxxxxxx&store_department_id=xxx&user_phone=12025550138

Response structure

Successful response results in returning by the server a JSON-object of following structure:

"status":"ok"

"marketing_actions_info":[
    {
        "name":"Limit action",
        "remaining_count":15,
        "till_date":"2017-11-24T19:44:58.489",
        "remaining_quantity":65,
        "remaining_discount":"1207894.00",
        "id":3596
     }
 ]

Response example

{
  "status":"ok",
  "marketing_actions_info":[
     {
        "name":"Limit action",
        "remaining_count":15,
        "till_date":"2017-11-24T19:44:58.489",
        "remaining_quantity":65,
        "remaining_discount":"1207894.00",
        "id":3596
     }
  ]
}