Skip to main content

Purchase Attributes and Position Attributes

In some cases (most often for analytics), it is necessary to save additional information for purchases, for example:

  • manager / cashier who performed the sale;
  • advertising source (flyer, leaflet, etc.);
  • store type;
  • any other business characteristics.

To pass such information to Sailplay, purchase attributes and position attributes are used, which can be passed:

  • during purchase creation;
  • during promotion calculation.

Main Usage Scenarios​

Analytics​

Purchase and product attributes are supported in the platform's analytical filters.
This allows for building reports and segments by additional order and position characteristics.

Use in Promotions​

In the conditions of promotions of the "Make a purchase" type, you can:

  • enable the "Specify characteristics" flag;
  • select purchase attributes and their values that will be considered when checking condition fulfillment.

By a similar principle, attributes can be used:

  • in conditions related to products;
  • in rewards (for example, "Product discount").

Examples of promotion attributes:

  • payment type (for example, payment_type attribute with values card or cash)
  • order receiving type (for example, delivery_type with values "Pickup" or "Delivery")
  • order source (for example, source with values: "MA", "website", "Aggregator", etc.)

Supported Data Types​

The following value types are supported for purchase and position attributes:

  • number (decimal)
  • string (string)
  • date (date)
  • text (text)

Purchase Attributes​

Creating a Purchase Attribute​

When creating a purchase attribute, its technical name and data type must be passed.
The response returns:

  • id — unique attribute identifier;
  • alias — technical name of the attribute.

Getting a List of Purchase Attributes​

A separate API method is used to get a list of all created purchase attributes.

Working with Purchase Attribute Values​

To add, delete, and get attribute values, the id or alias of the target attribute must be specified.

Adding and Deleting Attributes for Existing Purchases​

The Sailplay API allows for adding and deleting attributes and their values for purchases that were loaded previously.

This is especially useful for analytics and retrospective data enrichment.

Position Attributes​

Position attributes are passed directly within each cart position, and promotional mechanics can be configured on them (condition type "Buy product" or reward "Product discount" and option "Product with a certain attribute value by range," whose selection conditions depend on the position attribute type).

Position attributes can be:

  • number (decimal)
  • string (string)
  • date (date)
  • text (text)

Example cart structure with a position attribute:

cart={
  "1":{
    "sku":"0000",
    "price":100,
    "quantity":1,
    "position_attribute":"value"
  }
}

Position attributes can be used in analytics and in promotion conditions related to products.

Examples of using position attributes:

  • product type

Suppose you sell tickets that have two characteristics: child and adult. Since in the SKU context it's the same product, the attribute that is dynamic and depends on certain conditions is passed as a position attribute, for example "ticket_type":"Adult" or "ticket_type":"Child"

  • dynamic characteristic

Suppose you have a promotion giving a discount on the last size in stock. From an inventory perspective, the first or last pair of a certain size is the same SKU, but if, for example, the last pair is being scanned at checkout, you can pass a dynamic parameter, a position attribute, "last_size":"true," on which a promotion can be configured.