Cart and Products Categories

SailPlay implements the mechanism of processing the cart's content. The processing of the cart's content and the products categories can be required in the following cases: 

  1. When you need to implement logic for different rules of awarding bonus points for different products or different categories. 
  2. For analytics and statistics related to the cart's content. 

Operating Principle

Each product in the SailPlay system receives the product ID in your system (SKU). Similarly, each category in the SailPlay system receives an ID in your system. 

For each product, each category you should specify: 

  1. Name
  2. ID
  3. Conversion rate for rubles to points for the purchase of this product / purchase of the product from this category
  4. Image

Correspondingly, when submitting information about the purchase you need additional information about the cart's content(see here). 

When processing the cart's content the following rules are applied:

  1. If the product with this SKU or the group with this ID does not exist in SailPlay's data base, they are created automatically (without a name and other attributes). 

  2. If there is no special conversion rate for this product, it will be checked if there is a conversion rate for this category. If it does not exist, the default conversion rate is used.

  3. If the same product is submitted in one array multiple times, the amounts are added first.

 

Methods

  • /api/v2/basket/categories/add/ - adding a category
  • /api/v2/basket/categories/edit/ - editing category information
  • /api/v2/basket/categories/list/ - categories list

  • /api/v2/basket/attributes/add/ - adding a directory (attribute)
  • /api/v2/basket/attributes/edit/ - editing a directory
  • /api/v2/basket/attributes/list/ - directories list

  • /api/v2/basket/attributes/values/add - adding value for a directory (attribute)
  • /api/v2/basket/attributes/values/edit - editing value for a directory
  • /api/v2/basket/attributes/values/list - directory values list
  • /api/v2/basket/attributes/values/delete - deleting the directory value

  • /api/v2/basket/products/add/ - adding product information
  • /api/v2/basket/products/edit/ - editing product information
  • /api/v2/basket/products/list/ - all products list

  • /api/v2/basket/products/attributes/add/ - assigning an attribute and value to the product
  • /api/v2/basket/products/attributes/edit/ - editing attribute's value
  • /api/v2/basket/products/attributes/delete/ - deleting the product's attribute

 

/api/v2/basket/categories/add/ - adding a category

This method is used to add products' categories. You should keep in mind that if the category has been created before when submitting information about the purchase (see here),then when adding the category with this SKU using this method, a new entry in the data base will not be created; only relevant parameters (name, image, etc.) will be updated.

Request Format

Is the parameter mandatory? Parameter Name Parameter Description
yes token  see here
yes store_department_id  see here
yes sku  category ID in your system
no parent_sku  Parent category (sku). If it is not specified, the root category is set.
no name  Category name
no pic  Category image
no points_rate  Conversion rate from rubles to points. When this parameter is not specified, the value from settings is used. Format points_rate=0.45


Server Response

Parameter Name Parameter Description
status  Transaction status
sku  Category ID
create_date  Category creation date
parent_sku  Parent category
points_rate  Bonus points rate in the created category
pic  Category image URL

 

Server Response Example:

{
status: 'ok',
sku: 'sku_1',
name: 'category name',
parent_sku: 'sku_2'
create_date: '2014-03-05T16:30:30.513',
points_rate: '0.004',
pic: '//d39c94cu632zjz.cloudfront.net/static/absolute_url.jpg'
}

 

Errors codes

Code Description
-7000   The category name or sku are already in use by another category.

/api/v2/basket/categories/edit/ - editing category information

This method is used to edit category information. It should be noted that if some fields are not submitted in the request, then relevant attributes will not be changed for this category.To delete the parameter's value you should submit an empty string. 

Method

POST /api/v2/basket/categories/edit/

Request Format

Is the parameter mandatory? Parameter Name Parameter Description
yes token  See here
yes store_department_id  See here
yes sku  Category ID in your system
no parent_sku  Parent category (sku)
no name  Category name
no pic  Category image
no points_rate  Conversion rate from dollars to points. When this parameter is not specified, the value from settings is used. Format points_rate=0.45

 

Server Response

Parameter Name Parameter Description
status  Transaction status
sku  Category ID
create_date  Category creation date
points_rate  Bonus points rate in the created category
pic  Category image URL

 

Server Response Example:

{
status: 'ok',
sku: 'sku_1',
name: 'category name',
create_date: '2014-03-05T16:30:30.513',
points_rate: '0.004',
pic: '//d39c94cu632zjz.cloudfront.net/static/absolute_url.jpg'
}

 

Errors codes

Code Description
-7001  The category name is already in use by another category.
-7002  There is no category for the submitted sku

 

/api/v2/basket/categories/list/ - categories list

This method is designed to receive the list of categories for products that have been added with the use of relevant methods (see here and here).

Method

GET /api/v2/basket/categories/list/

 

Request Format

Is the parameter mandatory? Parameter Name Parameter Description
yes token  See here
yes store_department_id  See here
no sku   If it is specified, only information for the category with this sku is displayed. It is mutually exclusive with parent_sku
no parent_sku   It limits the list of received categories by the specified category and its child category(ies). If it is not specified, all categories are displayed

 

Server Response

Parameter Name Parameter Description
status  Transaction status
categories  Objects array with the following attributes:
sku  SKU (ID) in your system.
parent_sku  Parent category (sku)
name  Category name
points_rate  Category conversion rate
create_date   Creation date

 

Server Response Example: 

{
status: 'ok',
categories: [
{
sku: 'c_1',
parent_sku: 'sku_3'
name: 'electronics',
points_rate: '0.1000',
pic: '//d39c94cu632zjz.cloudfront.net/static/e.jpg'
},
{
sku: 'c_2',
parent_sku: 'sku_4'
name: 'food',
points_rate: '0.2500',
pic: '//d39c94cu632zjz.cloudfront.net/static/food.jpg'
},
....
]
}

 

/api/v2/basket/attributes/add/ - adding a directory (attribute)

This method is required to create some attribute for a product or a service. Products with the specified attribute can build a directory and be used to group products in the SailPlay's system. 

Method

POST /api/v2/basket/attributes/add/

 

Request Format

Is the parameter mandatory? Parameter Name Parameter Description
yes token  See here
yes store_department_id  See here
yes sku  SKU (ID) of the attribute in your system.
yes data_type  Data type stored in the attribute. It can have the following values: bool, date, float and text.
no name   Name. If it is not specified, the empty value is saved.
no pic   Product image file (not a link) 

Server Response

Parameter Name Parameter Description
status  Transaction status
sku  Product ID
parent_sku  Parent directory SKU (ID)
name  Directory Name 
data_type  Data type
values  Available values array

 

Server Response Example: 

{
status: 'ok',
sku: 'attribute_1',
parent_sku: 'attribute_2'
name: 'attribute name',
data_type: 'bool'
values: [sku: 'product_01', ‘value’: 'true'})]
}

/api/v2/basket/attributes/edit/ - editing a directory

This method is required to edit a directory (attribute). 
Only sku parameter is mandatory. Only parameters specified in the request will be changed.
To delete the parameter's value you should submit an empty string.

It should be noted that the attribute 'data_type' can't be changed.

Method

POST /api/v2/basket/attributes/edit/

 

Request Format

Is the parameter mandatory? Parameter Name Parameter Description
yes token  See here
yes store_department_id  See here
yes sku  SKU (ID) of the attribute in your system
no name  Name. If it is not specified, the empty value is saved.
no parent_sku   Parent directory SKU (ID): If it is not specified, the empty value is saved.

 

Server Response

Parameter Name Parameter Description
status  Transaction status
sku  Attribute ID
parent_sku  Parent directory SKU (ID)
name  Directory Name  
data_type  Data type

 

Server Response Example: 

{
status: 'ok',
sku: 'attribute_1',
parent_sku: 'attribute_4'
name: 'attribute name2',
data_type: 'bool'
values: [sku: 'product_01', ‘value’: 'true'})]
}

 

/api/v2/basket/attributes/list/ - directories list

This method is designed to receive the list of directories (attributes) that have been added with the use of relevant methods, as well as the array of sku values that have been assigned an attribute and its value.

Method

POST /api/v2/basket/attributes/list/

 

Request Format

Is the parameter mandatory? Parameter Name Parameter Description
yes token  See here
yes store_department_id  See here
no sku   If it is specified, only information for one directory is displayed. It is mutually exclusive with parent_sku
no parent_sku   It limits the list of received directories by the specified directory and its child directory(ies). If it is not specified, all directories are displayed.

Server Response

Parameter Name Parameter Description
status  Transaction status
attributes  Array of objects with the description of directories and the array of their values:
sku  Attribute ID
parent_sku  Parent directory SKU (ID)
name  Directory Name  
values   Array of available values (array of objects in form of {‘sku’: , ‘value’: })

 

Server Response Example: 

{
status: 'ok',
"attributes": [
{
sku: 'attribute_1',
parent_sku: 'attribute_4'
name: 'attribute name1',
values: [sku: 'product_01', ‘value’: 'true'}
{
sku: 'attribute_2',
parent_sku: 'attribute_4'
name: 'attribute name2',
values: [sku: 'product_02', ‘value’: 'null'}
]
}

The method returns 100 products on the page per request.

If sku is submitted, only information for one directory is displayed. If parent_sku is submitted the list of received directories will be limited by the specified directory and child directory(ies) for parent_sku.

/api/v2/basket/attributes/values/add - adding value for a directory (attribute)

This method is designed to add values for various created directories (attributes). Values and their names can be added for each attributes. The number of values for attributes is not limited

Method

POST /api/v2/basket/attributes/values/add/

 

Request Format

Is the parameter mandatory? Parameter Name Parameter Description
yes token  See here
yes store_department_id  See here
yes sku  SKU (ID) of the attribute in your system
no value_sku  Value name
no value  Attribute value according to the data_type of the attribute

 

Server Response

Parameter Name Parameter Description
status  Transaction status
values  Array of values for the specified directory (attribute) with names

 

Server Response Example: 

{
status: 'ok',
values: [sku: 'is_jnvls', ‘value’: 'true'})]

}

If sku already has a relevant attribute, an error will be returned:

{"status": "error", "message": "Value with such sku already exists for this attribute"}

If sku already has a relevant attribute, an error will be returned:

This method is required to edit values of a directory (attribute). 
Only sku parameter is mandatory. Only parameters specified in the request will be changed.
To delete the parameter's value you should submit an empty string.

It should be noted that the attribute 'data_type' can't be changed.

Method

POST /api/v2/basket/attributes/values/edit/

 

Request Format

Is the parameter mandatory? Parameter Name Parameter Description
yes token  See here
yes store_department_id  See here
yes sku  SKU (ID) of the attribute in your system
yes value_sku  Value name. It can't be changed
yes value  Attribute value according to the data_type of the attribute. It can be changed

 

Server Response

Parameter Name Parameter Description
status  Transaction status

 

Server Response Example: 

{
status: 'ok'
}

 

/api/v2/basket/attributes/values/list - directory values list

This method allows receiving an array of permitted values with their names for one of the attributes.

 

Method

POST /api/v2/basket/attributes/values/list/

 

Request Format

Is the parameter mandatory? Parameter Name Parameter Description
yes token  See here
yes store_department_id  See here
yes sku  SKU (ID) of the attribute in your system

 

Server Response

Parameter Name Parameter Description
status  Transaction status
values  Array of permissible values for the specified directory (attribute)

 

Server Response Example: 

{ status: 'ok',
"values": [
{
sku: 'product_1'
value: state_1}
{
sku: 'product_2'
value: state_2}
]
}

 

/api/v2/basket/attributes/values/delete - deleting the directory value 

This method allows removing values from a specified directory (attribute).

 

Method

POST /api/v2/basket/attributes/values/delete/

 

Request Format

Is the parameter mandatory? Parameter Name Parameter Description
yes token  See here
yes store_department_id  See here
yes sku  SKU (ID) of the attribute in your system
yes value_sku  The name of the value to be removed

 

Server Response

Parameter Name Parameter Description
status  Transaction status

 

Server Response Example: 

{
status: 'ok'
}

 

/api/v2/basket/products/add/ - adding product information

This method is required to add information about the product to SailPlay's system. You should keep in mind that information about products can be added to the SailPlay's system via the request of the purchase adding

Method

POST /api/v2/basket/products/add/

 

Request Format

Is the parameter mandatory? Parameter Name Parameter Description
yes token  See here
yes store_department_id  See here
yes sku  SKU (ID) of this product in your system
no name  Product name
no price  Product price
no category_sku  Category SKU (ID)
no points_rate  Conversion rate from rubles to points for this product.
no points_rate  Conversion rate from rubles to points for this product.

 

Server Response

Parameter Name Parameter Description
status  Transaction status
sku  Product ID
create_date  Product creation date
points_rate  Bonus points rate for the created product
price  Product price
pic  Product image URL
category_sku  Category sku
attributes  Product range attributes

 

Server Response Example: 

{
status: 'ok',
sku: 'product_sku_1',
name: 'product name',
create_date: '2014-03-05T16:30:30.513',
points_rate: '0.05',
price: '100.0000'
pic: '//d39c94cu632zjz.cloudfront.net/static/absolute_url.jpg',
category_sku: 'category sku'
attributes: []
}

 

Errors codes

Code Description
-7002  There is no category for the submitted sku
-7003  There is no product for the submitted sku or the name exists already

 

/api/v2/basket/products/edit/ - editing product information

This method is used to edit product information. 
Only sku parameter is mandatory. Only specified parameters will be changed.
To delete the parameter's value you should submit an empty string.

Method

POST /api/v2/basket/products/edit/

 

Request Format

Is the parameter mandatory? Parameter Name Parameter Description
yes token  See here
yes store_department_id  See here
yes sku  SKU (ID) of this product in your system
no name  Product name
no price  Product price
no category_sku  Category SKU (ID)
no points_rate   Conversion rate from rubles to points for this product.

 

Server Response

Parameter Name Parameter Description
status  Transaction status
sku  Product ID
create_date  Product creation date
points_rate  Bonus points rate for the created product
price  Product price
pic  Product image URL
category_sku  Category sku
attributes  Product range attributes

 

Server Response Example: 

{
status: 'ok',
sku: 'product_sku_1',
name: 'product name',
create_date: '2014-03-05T16:30:30.513',
points_rate: '0.05',
price: '100.0000'
pic: '//d39c94cu632zjz.cloudfront.net/static/absolute_url.jpg',
category_sku: 'category sku'
attributes: []
}

 

Errors codes

Code Description
-7002  There is no category for the submitted sku
-7004  The submitted name is already in use by another product
-7005  There is no product for the submitted sku

 

/api/v2/basket/products/list/ - all products list

This method is designed to receive the list of products that have been added with the use of relevant methods (see here and here).

Method

GET /api/v2/basket/products/list/

 

Request Format

Is the parameter mandatory? Parameter Name Parameter Description
yes token  See here
yes store_department_id  See here
no sku  Product sku. If it is specified, only information for one product is displayed.
no category_sku  Products category sku. It limits the list of products by the specified category and its child category(ies). If it is not specified, all products are displayed.
no page  Page number

 

Server Response

Parameter Name Parameter Description
status  Transaction status
num_pages  Number of pages
products  Objects array with the following attributes:
sku  SKU (ID) of the product in your system.
attributes  The object that contains the list and values of the product's attributes.
name  Product name
category_sku  The category of the product
points_rate  Conversion rate for this product
create_date  Creation date

 

Server Response Example: 

{
status: 'ok',
num_pages: 3,
products: [
{
sku: 'a_1',
name: 'notebook',
points_rate: '0.1000',
pic: '//d39c94cu632zjz.cloudfront.net/static/notebook.jpg',
      category_sku: 'e_1'
"attributes": [
               {
                   "sku": "attr1",
                   "values": [
                       {
                           "sku": null,
                           "value": "va3"
                       }
                   ],
                   "name": "first"
               }
           ],
},
{
sku: 'a_2',
name: 'tablet pc',
points_rate: '0.2500',
pic: '//d39c94cu632zjz.cloudfront.net/static/tablet.jpg',
category_sku: 'e_1'
"attributes": [
               {
                   "sku": "attr2",
                   "values": [
                       {
                           "sku": null,
                           "value": "va4"
                       }
                   ],
                   "name": "first"
               }
           ],
},
....
]
}

 

/api/v2/basket/products/attributes/add/ - assigning an attribute and value to the product

This method is designed to add directories (attributes) for created products. Different attributes with different values can be added for each product. The number of attributes is not limited.

Method

POST /api/v2/basket/products/attributes/add/

 

Request Format

Is the parameter mandatory? Parameter Name Parameter Description
yes token  See here
yes store_department_id  See here
yes sku  Product ID
yes attribute_sku  SKU of the created directory (attribute)
yes value_sku  Attribute value according to the data_type of the attribute

 

Server Response

Parameter Name Parameter Description
status  Transaction status

 

Server Response Example: 

{
status: 'ok'
}

/api/v2/basket/products/attributes/edit/ - editing attribute's value

This method is required to edit an attribute for a product.
To edit the attribute's value you should submit both an old and a new value.

It should be noted that the new value should correspond to the 'data_type' of the attribute (directory).

Method

POST /api/v2/basket/product/attributes/edit/

 

Request Format

Is the parameter mandatory? Parameter Name Parameter Description
yes token  See here
yes store_department_id  See here
yes sku  Product SKU
yes attribute_sku  SKU (ID) of the attribute in your system
yes value_sku_from  Attribute value before change
yes value_sku_to  Desired (new) attribute value

 

Server Response

Parameter Name Parameter Description
status  Transaction status

 

Server Response Example: 

{
status: 'ok'
}

/api/v2/basket/products/attributes/delete/ - deleting the product's attribute

This method allows removing values from a specified directory (attribute).

 

Method

POST /api/v2/basket/products/attributes/delete/

 

Request Format

Is the parameter mandatory? Parameter Name Parameter Description
yes token  See here
yes store_department_id  See here
yes sku  Product SKU
yes attribute_sku  SKU (ID) of the attribute in your system

 

Server Response

Parameter Name Parameter Description
status  Transaction status

 

Server Response Example: 

{
status: 'ok'
}