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, 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 following (per cart item):

  • marketing actions applied,
  • modified prices (that consider all discounts and mark-ups 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

Parameter is required Parameter Parameter description Data type Example
Yes token Details here See request URL example
token=qx6s4gsdvsdhsdsd
Yes store_department_id Details here integer
store_department_id=345 
Yes
  • cart
    • 1, 2, 3 ... n
    • sku
    • price
    • quantity
    • discount_points
    • min_price
  • JSON-object that contains necessary information about the cart items
    • Item sequence number (starting from 1)
    • Product ID used in your system
    • Total price for all units of given item
    • Total number of units of given item. It’s optional but if not specified “1” is used by default.
    • Number of bonus points to be deducted from original price as discount. It’s ptional, but if not specified “0” is used by default.
    • Minimal price a product can sold for. This can’t be discounted any further even if promo campaign applied defines a bigger discount in its settings. Parameter is optional.
  • JSON Objects
    • JSON String
    • JSON String
    • JSON Number
    • JSON Number
    • JSON Number
    • JSON Number
{"1":{"sku":"item1","price":1000,"quantity":1,"discount_points":0,"min_price":250}} 

qweasdzxcqweasdxcz

No promocodes An array containing promocode values that should be applied to a purchase. JSON Array
["summer2017"]
No card_numbers An array containing card values (e.g. loyalty program ID card, or special offer card) that should be applied to a purchase. Multiple values can be passed to an array divided by comma. JSON Array
["290000000236543"]
No verbose Adds extended data to the response if passed with value “1”. If not passed or the value is “0” then extended data will not be returned.
“Extended data” refers to marketing_actions_applied array and marketing_actions array of position array. integer
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 payment method is be created in SailPlay panel. This is a prerequisite for getting 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 min_price parameter. min_price can be represented by an accounted cost of product or any other price threshold, selling a product below which would be income-wise unreasonable.
  • If the amount 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:

ParameterParameter descriptionData typeExample
status Request status JSON String
"status":"ok"
  • marketing_actions_applied
    • client_msg
    • service_msg
    • name
    • alias
  • An array with the objects of promo campaigns that were applied to the cart. Each object contains following set of string-value pairs:
    • Message to be displayed to a customer
    • Message to be displayed to a cashier
    • Promo campaign name
    • Promo campaign id
  • JSON Array
    • JSON String или null
    • JSON String или null
    • JSON String
    • JSON String
"marketing_actions_applied":[
   {
      "client_msg":null,
      "service_msg":null,
      "name":"Bonus",
      "alias":"60 pre"
   }
]

------------------------------

possible_marketing_actions An array with the objects of promo campaigns that were applied to the cart. Each object contains same set of string-value pairs as marketing_actions_applied same as marketing_actions_applied same as marketing_actions_applied
  • cart
    • total_price
    • total_discount_points_max
    • total_points
    • positions
      • category
        • sku
        • id
        • name
      • product
        • sku
        • id
        • name
      • discount_points_max
      • reverse_points_rate
      • price
      • expiry_info
      • new_price
      • min_price
      • num
      • marketing_actions
      • quantity
      • points_rate
      • discount_points
      • points
    • positions_count
    • id
  • Cart object that contains following data:
    • Total price of cart after all promo campaigns were applied
    • Total max amount of bonus points that can be used as payment method. Rules that define this value are to be set in SailPlay admin panel.
    • Amount of bonus points that user will get for the current purchase (in accordance with the setting in SailPlay admin panel). 
    • An array containing the objects for each cart item. Each object contains following set of objects and string-value pairs:
      • An object of product category data:
        • Category id in source (Client) system
        • Category id in SailPlay
        • Category name
      • An object containing product data:
        • Product id in source (Client) system
        • Product id in SailPlay
        • Product name
      • Max amount of bonus points for a given cart item that can be used as payment method. Rules that define this value are to be set in SailPlay admin panel.
      • Multiplicator that converts bonus points used to pay for an item to amount of money by which the original price will be eventually reduced. Rules that define this value are to be set in SailPlay admin panel.
      • Original price value of the item
      • Price of an item after applying all the discounts.
      • Min possible price for the item irrespective of the sum of total discounts. Value should be calculated on side of a web-store system / POS in accordance with business logic needed. min_price can be represented by an accounted cost of product or any other price threshold, selling a product below which would be income-wise unreasonable.
      • Ordinal number of an item in the cart. Can be used to sort and compare items from response against the items on Client side
      • An array that contains promo campaigns that were applied to this particular item.
      • Quantity of an item in the cart
      • Multiplicator that was used to calculate the amount of bonus to be credited to user’s account for purchasing this item. Rules that define this value are to be set in SailPlay admin panel.
      • Amount of bonus points that will be deducted from original price.
      • Amount of bonus to be credited to user’s account for purchasing this item.
    • Number of unique items in the cart. NOTE that this parameter is not affected by the “quantity” of any item.
    • Transaction id.
  • JSON Object
    • JSON String
    • JSON Number
    • JSON Number
    • JSON Array
      • JSON Object
        • JSON String
        • JSON Number
        • JSON String
      • JSON Object
        • JSON String
        • JSON Number
        • JSON String
      • JSON Number
      • JSON Array
      • JSON String
      • JSON String
      • JSON String
      • JSON Number
      • JSON Array
      • JSON String
      • JSON String
      • JSON Number
      • JSON Number
    • JSON Number
    • JSON Number
"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:

ParameterParameter descriptionData typeExample
count Number of times promo campaign can be further applied for a given customer JSON Number or null
"count":1
total_quantity_applied Number of products promo campaign can be further applied to JSON String or null
"total_quantity_applied":"10"
till_date Date when limits per user will be reset JSON String or null
"till_date":"2017-11-19T19:44:58.489"
total_discount Discounts fund (in money terms) that is available for a customer to use till the end of a given period.. JSON String or null
"total_discount":"207894.00"

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

Method can be used for querying limits that are remained 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 to specify 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 purchase can also be set. Moreover, these conditions can be even more specific defining the number of times 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, campaign can take in 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.

Parameter is required Parameter Parameter description Example
Yes token Details here
token=dqgfsd66asdhgds87ssd
да user_phone, email or origin_user_id Customer ID. Details here
user_phone=12025550138
да store_department_id Details here
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:

ParameterParameter descriptionData typeExample
status Request status JSON String
"status":"ok"
  • marketing_actions_info
    • name
    • remaining_count
    • till_date
    • remaining_quantity
    • remaining_discount
    • id
  • An array with limits per user data:
    • Promo campaign name
    • Remaining number of promo campaign applications
    • Date when the limits will be reset
    • Number of products promo campaign can be further applied to
    • Discounts fund (in money terms) that is available for a customer to use till the end of a given period
    • Promo campaign id
  • JSON Array
    • JSON String
    • JSON Number
    • JSON String
    • JSON Number
    • JSON String
    • JSON Number
"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
     }
  ]
}