1. Fixed Combos

Combo accounts documentation

In addition to the Promotions & Deals functionality, BEES also possesses a mechanic that allows the grouping of products to be sold as one, which is referred to as Fixed Combo.

Fixed Combos have the purpose of offering POCs products that, if bought through the combo, would have a substantial price advantage if compared to buying a unique product. On top of having superior pricing, Fixed Combos can also offer free goods products align with promotional products for a single combo.

To better illustrate the usability of Fixed Combos below is a use case:

  • Fixed Combo - Buy 5 Product A + 3 Product B + Earn Product C for free.

The main properties to create a Fixed Combo as well as the explanation of the mechanics are described in the document below.

Payload Breakdown

1.1 Combo Accounts

For Fixed Combos, BEES has the granularity of allowing once certain POCs to view and purchase it. The property below is the use responsible for verifying what POCs should be able to view, interact and purchase the combos:

  • vendorAccountIds:

    • As described below, the vendorAccountIds are unique identification for the POC. Therefore, it is where BEES will look to verify if a specific Combo can be displayed to a specific set of accounts, and therefore return the combo to the accounts configured in this property.

    • It is important to notice that the property can be populated with a single account or a list of them.

Property

Description

Required

Example

vendorAccountIds

One or more account IDs can be sent at once on this field. If the combo will be set to multiple accounts, all accounts related to this combo can be included here, with no need to send the same combo many times only to associate to numerous accounts.

true

34521337000166, 02342525300, 87575758400 

{
  "vendorAccountIds": [
    "34521337000166",
    "02342525300",
    "87575758400"
  ]
}

 

1.2 Combo Items

A crucial element of Fixed Combos are the products that are being offered within the combo itself.
Therefore, in order to specific which products will be included, as well as the quantity offered for each one, is necessary to understand the following properties:

Regular Products:

  • VendorItemID:

    • The vendor item id, as explained throughout this document, is the unique identifier of the product from the Partner’s perspective. It can be the same as the SKU code.

  • VendorComboItemId

    • The unique identifier of the product within the Combo itself. It can be the same of the vendorItemId however it can also be populated with another value to better describe the product within the the combo.

  • quantity

    • This property is very straightforward and it defines the amount of the specific product configured that is being offered for this Fixed Combo,

Property

Description

Required

Example

combos.[].items.[].vendorItemId

Item id, same SKU.

true

1234567892

combos.[].items.[].vendorComboItemId

Combo item id.

true

demo-store-combo-001

combos.[].items.[].quantity

The item quantity.

true

5 

{
    "items": [
          {
              "vendorItemId": "1234567892",
              "vendorComboItemId": "demo-store-combo-001",
              "quantity": 5,
              "returnable": false
          },
          {
              "vendorItemId": "1234567891",
              "vendorComboItemId": "demo-store-combo-002",
              "quantity": 3,
              "returnable": false
          }
    ]
}

 

1.3 Combo Free Goods

As mentioned in the beginning of this document, Fixed Combos can also offer products without any cost. Those products without cost are referred to as free goods.

Therefore if a Fixed Combo will offer a product for free is necessary to specify, similar to the items object described above, the products that will be earn for free by the POC. Below are the properties within the Free Goods object that designates the free goods products within a combo.

Free GoodsProducts:

  • VendorItemID:

    • The unique identifier of the product that will be offered for free within the Fixed Combo. As mentioned before, the vendorItemId can be the same as the SKU code.

  • VendorComboItemId

    • The unique identifier of the product within the Combo itself. It can be the same of the vendorItemId however it can also be populated with another value to better describe the product within the the combo.

  • quantity

    • The amount of products that will be configured without any value within the combos.

Property

Description

Required

Example

combos.[].freeGoods.items.[].vendorItemId

Item id, same SKU.

true

1234567895

combos.[].freeGoods.items.[].vendorComboItemId

Combo item id.

true

demo-store-combo-fg

combos.[].freeGoods.quantity

quantity

true

2 

{
  "freeGoods": [
        {
            "items": [
                  {
                      "vendorItemId": "1234567895",
                      "vendorComboItemId": "demo-store-combo-fg",
                      "returnable": false
                  }
            ],
            "quantity": 1
        }
      ]
  }

 

1.4 Combo General Information

Within Fixed Combos, BEES also offers the flexibility to improve the communication for specific combo, such as specifying images, titles and description. On top of that, it is also mandatory to inform BEES the combo type which can be configured based on what is being offered within the combo.

To better manage the availability of the combos being created, BEES counts with two properties that defines when the combo will start and when it will end. Thus, within that time window is when the combo will be available for purchases.

Below are general properties for Fixed Combos as well as a brief description:

Identifiers:

  • Type

    • The combo type is a very important information which will define what are the products being offered within combo. For instance if the combos contains only products with a discounted price, then the type must be set as D (for Discount). If the combos is being offered with a mix of products and free goods, then type must be set as FG (for combos containing free goods).

  • vendorComboId

    • The unique identifier of the combo. This property must be set to better determine and identify the combo once an order has been placed as well as to manage and update information for existing combos.

Availability

  • startDate

    • The date in which the combo will appear for the POCs in the BEES Application, allowing POCs to view, interact and purchase the combo.

  • endDate

    • The date in which the combo will disappear in the BEES Application, thus, removing the Fixed Combo from BEES and not allowing any more interaction and purchases

Metadata

Fixed Combos will appear on a specific area of the application, which is under the Combos options demonstrated below in the screenshot. Given that scenario, it is possible to populate the Combo Metadata to raise the engaged and drive attention to the combo.

  • Title

    • The title that will be displayed to users when they access the Combo section within the BEES Application. It is important to create a title that will have a clear message of what the combos offers, such as “Buy 5 Products A Earn 1 Product B”

  • Description

    • The description of the combo that will be displayed under the title. It should be used to increase the awareness of the Combo and bring support to the combo title.

  • Image

    • The image that will be displayed to the users when they access the Combo Section within BEES. It is recommended that the image contains a clear vision of the products being offered as well as emphasizing the advantage of the combos, such as demonstrating that there are products that can be earned for free.

 

Property

Description

Required

Example

combos.[].image

The image used as the combo background.

false

"https://www.ambev.com.br/sites/g/files/wnfebl5836/files/styles/webp/public/paragraphs/product_size/2022-09/Budweiser%20990ml.png.webp?itok=ex3dF8xB"

combos.[].vendorComboId

The id of the combo

true

DM-37936

combos.[].title

The combo title.

true

Test

combos.[].type

The combo type where D stands for Discount, FG stands for Free Good, DT stands for Digital Trade and DT3P stands for Digital Trade 3P.

true

FG

combos.[].description

The combo description, with mode details on the deal.

true

"Comprando 5 Antarctica SUBZERO e mais 3 Antarctica, ganhe 1 Budweiser grátis"

combos.[].startDate

The combo activation date. It should be in UTC timezone.

true

2022-12-13T00:00:00+00:00

combos.[].endDate

The combo deactivation date. Needs to be after the startDate. It should be in UTC timezone.

true

2023-12-31T00:00:00+00:00 

{
  "image": "https://www.ambev.com.br/sites/g/files/wnfebl5836/files/styles/webp/public/paragraphs/product_size/2022-09/Budweiser%20990ml.png.webp?itok=ex3dF8xB",
  "vendorComboId": "demo-store-combo-001",
  "title": "Compre 5 Antarctica SUBZERO + 3 Antarctica, Gratis 1 Budweiser",
  "type": "FG",
  "description": "Comprando 5 Antarctica SUBZERO e mais 3 Antarctica, ganhe 1 Budweiser grátis.",
  "startDate": "2023-08-22T00:00:00+00:00",
  "endDate": "2025-12-31T00:00:00+00:00"
}

 

2. Sample and Curl

 

 
curl --location --request POST 'https://services-uat.bees-platform.dev/data-ingestion-relay-service/v1' \
  --header 'Authorization: Bearer {token}' \
  --header 'country: BR' \
  --header 'requestTraceId: COMBO_DELETION_NESTLE_EC_TEST' \
  --header 'Content-Type: application/json' \
  --header 'Cookie: incap_ses_1478_2295550=TXOaLccxJgzoI2upwumCFGar52QAAAAAPNmaoudsW3z+KvrsunLE0A==; nlbi_2295550=6LkxC2eYgXZ0Jo2X316kQQAAAABiohr1MkvZw8dFU93+k4F3' \
  --data-raw '{
      "entity": "COMBOS_ACCOUNTS",
      "version": "v3",
      "payload": "{\"vendorAccountIds\":[\"62691196000165\"],\"combos\":[{\"image\":\"https://www.ambev.com.br/sites/g/files/wnfebl5836/files/styles/webp/public/paragraphs/product_size/2022-09/Budweiser%20990ml.png.webp?itok=ex3dF8xB\",\"vendorComboId\":\"demo-store-combo-001\",\"title\":\"Compre5AntarcticaSUBZERO+3Antarctica,Gratis1Budweiser\",\"type\":\"FG\",\"description\":\"Comprando5AntarcticaSUBZEROemais3Antarctica,ganhe1Budweisergrátis.\",\"startDate\":\"2023-08-22T00:00:00+00:00\",\"endDate\":\"2025-12-31T00:00:00+00:00\",\"items\":[{\"vendorItemId\":\"1234567892\",\"vendorComboItemId\":\"demo-store-combo-001\",\"quantity\":5,\"returnable\":false},{\"vendorItemId\":\"1234567891\",\"vendorComboItemId\":\"demo-store-combo-002\",\"quantity\":3,\"returnable\":false}],\"freeGoods\":[{\"items\":[{\"vendorItemId\":\"1234567895\",\"vendorComboItemId\":\"demo-store-combo-fg\",\"returnable\":false}],\"quantity\":1}],\"limit\":{\"daily\":9999,\"monthly\":999999},\"price\":150}]}"
}'