Buy N items and get M of the same item for free

Specify in the price list how many items need to be purchased and how many the customer will receive as a gift.

Structure

<promos>
   <promo id="promo ID" type="n plus m">
      <start-date>promo start date</start-date>
      <end-date>promo end date</end-date>
      <description>summary</description>
      <url>promo on the store's site</url>
      <purchase>
        <required-quantity>number of full-price items</required-quantity>
        <free-quantity>number of bonus items</free-quantity>
        <product offer-id="offer ID participating in promo"/>
        ...
        <product category-id="category ID participating in  promo"/>
        ...
      </purchase>
   </promo>
</promos>

Attributes and elements


Element/attribute	Description	Required
Attribute `id`	ID of the promotion. May not be identical to the IDs of loyalty programs or other promotions. It may contain only numbers and Latin letters. The maximum length of `id` is 20 characters. Attention. Specific offers may only participate in one promo or loyalty program. If an offer is included in multiple promos or loyalty programs, one will be selected for it at random.	Required
Attribute `type`	Type of promo — `n plus m`.	Required
`start-date` `end-date`	Date and time when the promo starts. Date and time the promo ends. Permissible formats: `YYYY-MM-DD` — Date: year, month, day (time zone of the region where the store is located). `YYYY-MM-DD` `hh:mm` / `YYYY-MM-DDThh:mm` — Date and time (time zone of the region where the store is located). `YYYY-MM-DD` `hh:mm:ss` / `YYYY-MM-DDThh:mm:ss` — Date and time with seconds (time zone of the region where the store is located). `YYYY-MM-DD` `hh:mmZ` / `YYYY-MM-DDThh:mmZ` — Date and time (`Z` — time zone, for example, +0300). `YYYY-MM-DD` `hh:mm:ssZ` / `YYYY-MM-DDThh:mm:ssZ` — Date and time with seconds (`Z` — time zone, for example, +0300). Examples `2018-09-01` `2018-09-01 09:00` `2018-09-01 09:00:01` `2018-09-01 09:00+0500` `2018-09-01 09:00:01+0500`	Optional
`description`	Brief description of the promo in Russian. Maximum of 500 characters. You can use XHTML markup, but only as a `CDATA` block of character data.	Optional
`url`	Link to the promotion description on the store's website. Link may not exceed 2048 symbols. Cyrillic links are permitted. The URL address must conform to the RFC 3986 standard.	Optional
`purchase`	Information about items participating in the promotion.	Required
Elements in `purchase`
`required-quantity`	Number of items (in individual units) that must be purchased to receive gift. Only numeric values may be entered. The maximum value is 24. The default value is 1 (one product).	Required
`free-quantity`	The number of items the customer will receive as a gift. The maximum value is 24.	Required
`product`	Items and/or categories that the promotion applies to. Attributes: `offer-id` — Offer ID. `category-id` — Category ID. Each `product` element corresponds to a single item or category. A `purchase` element may contain multiple `product` elements.	Required


Element/attribute	Description	Required
Attribute `id`	ID of the promotion. May not be identical to the IDs of loyalty programs or other promotions. It may contain only numbers and Latin letters. The maximum length of `id` is 20 characters. Attention. Specific offers may only participate in one promo or loyalty program. If an offer is included in multiple promos or loyalty programs, one will be selected for it at random.	Required
Attribute `type`	Type of promo — `n plus m`.	Required
`start-date` `end-date`	Date and time when the promo starts. Date and time the promo ends. Permissible formats: `YYYY-MM-DD` — Date: year, month, day (time zone of the region where the store is located). `YYYY-MM-DD` `hh:mm` / `YYYY-MM-DDThh:mm` — Date and time (time zone of the region where the store is located). `YYYY-MM-DD` `hh:mm:ss` / `YYYY-MM-DDThh:mm:ss` — Date and time with seconds (time zone of the region where the store is located). `YYYY-MM-DD` `hh:mmZ` / `YYYY-MM-DDThh:mmZ` — Date and time (`Z` — time zone, for example, +0300). `YYYY-MM-DD` `hh:mm:ssZ` / `YYYY-MM-DDThh:mm:ssZ` — Date and time with seconds (`Z` — time zone, for example, +0300). Examples `2018-09-01` `2018-09-01 09:00` `2018-09-01 09:00:01` `2018-09-01 09:00+0500` `2018-09-01 09:00:01+0500`	Optional
`description`	Brief description of the promo in Russian. Maximum of 500 characters. You can use XHTML markup, but only as a `CDATA` block of character data.	Optional
`url`	Link to the promotion description on the store's website. Link may not exceed 2048 symbols. Cyrillic links are permitted. The URL address must conform to the RFC 3986 standard.	Optional
`purchase`	Information about items participating in the promotion.	Required
Elements in `purchase`
`required-quantity`	Number of items (in individual units) that must be purchased to receive gift. Only numeric values may be entered. The maximum value is 24. The default value is 1 (one product).	Required
`free-quantity`	The number of items the customer will receive as a gift. The maximum value is 24.	Required
`product`	Items and/or categories that the promotion applies to. Attributes: `offer-id` — Offer ID. `category-id` — Category ID. Each `product` element corresponds to a single item or category. A `purchase` element may contain multiple `product` elements.	Required

Example

Buy two bags of dog food and get the third free:

<promo id="Promo2Plus1" type="n plus m">
  <start-date>2018-02-01 09:00:00</start-date>
  <end-date>2018-03-01 22:00:00</end-date>
  <description>Купи 2 упаковки корма и получи третью в подарок!</description>
  <url>http://best.seller.ru/promos/2plus1</url>
  <purchase>
    <required-quantity>2</required-quantity>
    <free-quantity>1</free-quantity>
    <product offer-id="55"/>
    <product offer-id="66"/>
    <product category-id="1"/>
    <product category-id="2"/>
  </purchase>
</promo>