Skip to main content

Promotion Calculation for Cart

The Sailplay API provides several mechanisms for promotion calculation.

Promotion Calculation for Cart​

The /marketing-actions/calc/ method (see /api/v2/marketing-actions/calc/) is the main tool for promotion calculation and solves several tasks at once:

  • Applies promotions to the cart and updates product costs according to promotion configurations.
  • Displays a list of promotions that can be applied to the cart under additional conditions.
  • Saves information about the order and applied promotions in the database with the possibility of its subsequent use.

In addition to authorization data, the request must contain a JSON string with information about products in the cart (cart): their identifier in your system (SKU), position cost (product of quantity and price per unit), and quantity.

Important

For any changes in the cart composition, it is necessary to send a request for promotion recalculation.

As a result of the request, you will receive an object consisting of three main arrays:

  • marketing_actions_applied — applied promotions. Contains information about applied promotions that needs to be displayed on the checkout page in the corresponding field.
    Important: it is possible to indicate exactly which promotions triggered for each of the products (optional).
  • possible_marketing_actions — possible promotions. Contains information about those offers that can be applied to the client under additional conditions. For example: "Order a photobook and interior printing and print 100 photos for free."
  • cart — cart array. Contains the composition of the cart passed in the request and modified product prices if any Sailplay promotions were applied.
Useful

The cart object contains the id key — the cart identifier in the Sailplay database.
This identifier can be passed in requests for working with purchases (see /api/v2/purchases/new/) in the cart_id parameter. In this case, there is no need to pass the cart composition again.

Passing Client Identifier​

Passing a client identifier is not mandatory in the request. However, depending on the audience settings of the created promotions, the result may differ for a request with an identifier and without one.

If client data was not passed in the request, only promotions configured for all clients (including non-participants of the loyalty program) will be applied to the cart. Personal offers aimed at a specific audience (e.g., having a certain tag) will not be applied.

If an identifier is present in the request, a client search and their assigned tags will be performed. After this, matching of tags with audience settings of active promotions will be checked and those for which tags match will be applied.

Passing Department Identifier​

The /api/v2/marketing-actions/calc/ method provides the ability to perform promotion calculation in another department, different from the one specified in store_department_id.

To do this, one of the parameters must be passed in the request:

  • target_dep_id — department identifier in Sailplay
  • target_dep_origin_id — your internal identifier that was specified when creating the department (see /api/v2/partners/departments/create/)

Additional Parameters​

Optionally, if provided by business logic, an additional parameter min_price can be passed for each position in the receipt — the minimum product cost, which cannot be reduced when applying promotions. The parameter must be calculated on the website or checkout software side.

The size of the desired bonus points deduction against a discount is passed with a separate dicount_points_writeoff parameter.

verbose​

The verbose key serves to display a list of restrictions on promotion application, if they were specified during creation.

Data modification concerns only the marketing_actions_applied array and the marketing_actions array nested in the positions object.

  • verbose=1 — output additional data
  • verbose=0 — do not output additional data

When passing verbose=1, additional fields will be added to the response:

  • count — remaining number of promotion applications for the user
  • total_quantity_applied — remaining number of products to which the promotion discount can apply
  • till_date — expiration date of restrictions for the user
  • total_discount — remaining amount that the user can receive as a discount

Example response fragment:

{
  "marketing_actions_applied": [
    {
      "count": 5,
      "total_quantity_applied": null,
      "service_msg": "6fcc3ebd-b57c-11e7-a265-000c29bf15f9",
      "name": "Percentage price from 20.10.2017 (531)",
      "alias": "6fcc3ebd-b57c-11e7-a265-000c29bf15f9",
      "client_msg": "6fcc3ebd-b57c-11e7-a265-000c29bf15f9",
      "till_date": "2017-11-19T19:44:58.489",
      "total_discount": "207894.00"
    }
  ]
}

The promocodes parameter is a JSON array with a list of promocodes passed along with the cart (order) for promotion calculation.

Applying Promotions to Cart Without Saving Result​

The /marketing-actions/calc/light/ method (see /api/v2/marketing-actions/calc/light/) is completely analogous to /marketing-actions/calc/ and accepts the same parameters in the request.

Difference: the result is not saved in the Sailplay database and will be unavailable for further use when working with purchases.