Add Up-Sell Offers for Products Having Dynamic Characteristics

An Up-Sell Offer is a pop-up containing an offer to replace one of the products at checkout with another one. It opens in a modal window on top of a checkout page and can contain several products at once. If the customer selects one of them, the initial product gets removed from the checkout page, and the selected product from the offer is added to it.

The offer can be shown to the customer in the following cases:

• When visiting a checkout page - the moment the customer clicks on a checkout link and adds a product to the checkout page
• When leaving a checkout page - the moment the customer's mouse cursor goes beyond the active area of the browser window with the opened checkout page
• In both cases:
  • The contents of each offer are managed separately
  • The offer will not be displayed when leaving a checkout page if the customer has already replaced one of the products on the checkout page

All products in an up-sell offer have dynamic characteristics, i.e., you transfer their properties in a request.

Use up-sell offers, for example, to offer your customer the same product as the one they chose themselves, but with advanced features (e.g., support for more devices), additional options (technical support), subscription condition modifications (e.g., auto-renewal or another term).

1. The customer selects one or several products on your end
2. You send a request to generate a checkout link. Transfer the following in the request:
   • The data of the products (products) selected by the customer and to be added to the checkout page
   • The data of the additional products (upsell) to be suggested for purchasing from the up-sell offer to replace one of the products already present on the checkout page

3. In response to the request, you receive a checkout link. This link redirects your customer to a checkout page on our end.
   Only one purchase can be made through this link (similarly, as for all products with dynamic characteristics)
4. The customer follows the link to the checkout page
5. The checkout page opens with an up-sell offer in a modal window. 
   The up-sell offer contains the data of the products from object upsell. In addition, special names (upsell.products.name_for_upsell) are used for the products that will be visible only in the offer window.

6. If the customer chooses a product from the offer: 
   • The product for which the up-sell offer has been shown is removed from the checkout page
   • Instead, the product chosen by the customer from the up-sell offer is added to the checkout page. Note that the product added has the name transferred in parameter upsell.products.name
   • The modal window closes

If the customer closed the up-sell offer (without choosing one of the products in it), the initial product the data of which had been transferred in parameter products would remain on the checkout page. The customer cannot re-open the up-sell offer after it has been closed.

Note that in the example, no parameter containing subscription data (products.subscription) is being transferred in parameter products, thus the initial product has no automatically renewable subscription at checkout. However, subscription data (upsell.products.subscription) is being transferred for the products from the up-sell offer. Therefore, when replacing the initial product with the product from the up-sell offer, the section for the automatically renewable subscription appears on the checkout page.

1. The customer selects one or several products on your end
2. You send a request to generate a checkout link. Transfer the following in the request:
   • The data of the products (products) selected by the customer and to be added to the checkout page
   • The data of the additional products (upsell_exit) to be suggested for purchasing from the up-sell offer to replace one of the products already present on the checkout page
3. In response to the request, you receive a checkout link. This link redirects your customer to a checkout page on our end
   Only one purchase can be made through this link (similarly, as for all products with dynamic characteristics)
4. The customer follows the checkout link to the checkout page and sees the products the data of which has been provided in parameter products
5. If the customer tries to leave the checkout page and moves the cursor outside the active area of the browser window, the up-sell offer opens in a modal window. It contains the data of the products from object upsell_exit. In addition, special names (upsell.products.name_for_upsell) are used for the products that will be visible only in the offer window.

1. The customer selects one or several products on your end
2. You send a request to generate a checkout link. Transfer the following in the request:
   • The data of the products (products) selected by the customer and to be added to the checkout page
   • The data of the additional products (upsell) to be suggested for purchasing from the up-sell offer to replace one of the products already present on the checkout page
   • The data of the additional products (upsell_exit) to be suggested for purchasing from the up-sell offer to replace one of the products already present on the checkout page
3. In response to the request, you receive a checkout link. This link redirects your customer to a checkout page on our end
   Only one purchase can be made through this link (similarly, as for all products with dynamic characteristics)
4. The customer follows the checkout link to the checkout page
5. The checkout page opens with an up-sell offer in a modal window
   The up-sell offer contains the data of the products from object upsell. In addition, special names (upsell.products.name_for_upsell) are used for the products that will be visible only in the offer window.
6. The customer closes the offer without selecting any of the products from it (his condition must be met for the second up-sell offer to be displayed when leaving the checkout page)
7. If the customer tries to leave the checkout page and moves the cursor outside the active area of the browser window, the up-sell offer opens in a modal window. It contains the data of the products from object upsell_exit. In addition, special names (upsell.products.name_for_upsell) are used for the products that will be visible only in the offer window

The description is given using the example of the offer that opens when visiting the checkout page. If you want to set up offers that open when leaving the checkout page, use the same parameters, but inside object upsell_exit.

An up-sell offer pops up in a modal window. It contains the following elements:

• Window name - It is part of the template and is not managed via the API
• Offer title – You transfer it in the request (upsell.name)
  For example, it may be the name of the product for which you want to suggest a replacement, or any other text of your choice
• Up-sell description – You transfer it in the request (upsell.description)
  It is an optional text to be displayed below the title
• Up-sell products – You transfer it in the request (upsell.products)
  Each product contains the following elements:
  • Up-sell product name – You transfer it in the request (upsell.products.name_for_upsell). You can transfer from 1 to 3 products.
    It may differ from the name the customer will see at checkout after accepting the offer. You can use this feature, for example, to show short names for up-sell products in your offer
  • Up-sell product price – It is calculated based on the data you transfer in the request: price per up-sell product item (upsell.products.price), up-sell product quantity (upsell.products.quantity). The price is also influenced by VAT charging. It is included in accordance with your Agreement you transfer in the request
  • Up-sell product purchase benefit – You transfer it in the request (upsell.products.benefit).
    This is an optional informational value. It does not affect the final price calculation anyhow. It is only displayed in the offer. The following additional text ("Benefit") will be displayed next to the amount money. This text is part of the template and is not managed via the API.
• Confirmation button - This element is part of the template and is not managed via the API. If the customer clicks this button, the product accepted from the offer window using the radio button is added to the checkout page. The product for which up-selling is offered gets removed from the checkout page.
• Reject icon – It depends on the design of your up-sell offer. You can use an icon button or a text button. This element is part of the template and is not managed via the API. If the customer clicks the button, the modal window closes. No product replacement happens at checkout. The checkout page will contain the products the customer selected initially.
• Image – You transfer it in the request (upsell.picture_url)
  It is an optional element and is only available when using a customized design template. If you want to use a customized offer template, write to ecommerce@noventiq.com describing the changes you require to be made to the default template. 
  You can use an image of a replacement product, a promotion banner, or any other image of your choice. If an image is not transferred or its URL is unavailable, it is not displayed in the offer window. The offer template does not display any error messages/empty elements or placeholders to the customer. The image will be scaled if its size differs from the place provided by the template

An original product is a product on our end. Its default property values are taken for product characteristics that are not transferred in your request.

To add several products to a checkout page, different original products must be used. You can use the same original product (or different ones if you want default properties to be different) for replacement products suggested by an up-sell offer.

The request uses the following parameters to transfer IDs of original products:

• Products to be added at checkout (products)
• Products with up-sell offers at checkout (upsell.product_id / upsell_exit.product_id)
• Up-sell products to be displayed (upsell.products / upsell_exit.products)

Parameter products transfers the products to be added to the checkout page. These are the products that the customer has decided to purchase.

• The ID of the original product must be transferred in products.id per product in the array. The default property values are taken from this original product
• If you want to add several products to the checkout page, you need to use different original products for them (standard logic)

Parameter upsell.product_id / upsell_exit.product_id transfers the ID of the product existing on the checkout page. The up-sell offer is to be displayed for this product. If the customer selects one of the products from the up-sell offer, the original product is removed from the checkout page. The selected product is added to the checkout page instead. 

• It must be one of the products to be added to the checkout page (products); i.e. the ID in upsell.product_id / upsell_exit.product_id must be equal to one of the IDs in products.id
• Identifiers in upsell.product_id and upsell_exit.product_id may differ from each other

Parameter upsell.products / upsell_exit.products transfers the products to be displayed in the up-sell offer. If the customer chooses to purchase one of these products, it is added to the checkout page. The dynamic data for adding these products to the checkout page is also transferred inside the array of upsell.products / upsell_exit.products.

• The ID of the original product must be transferred in upsell.products.id / upsell_exit.products.id per product in the array. The default property values are taken from this original product.
• Parameter upsell.products.id / upsell_exit.products.id must meet the following conditions:
  • Can be the same as the ID of the product for which the up-sell offer is displayed on the checkout page (upsell.product_id / upsell_exit.product_id)
  • Can differ from upsell.product_id / upsell_exit.product_id. In this case, it must not be the same as the ID of any other product on the checkout page (products.id)
• Identifiers in upsell.product_id and upsell_exit.product_id may differ from each other

The description is given using the example of the offer that opens when visiting the checkout page. If you want to set up offers that open when leaving the checkout page, use the same parameters, but inside object upsell_exit.

Additional Parameters are non-customer facing service data. This data does not affect the checkout process. You can transfer them in a request. In this case they will be saved into the order and used in the future.

Note that additional parameters are saved into the order in bulk with no reference to any product.

You can use additional parameters together with up-sell offers. This will allow you to update or add additional paramaters to the order if the customer chooses to purchase a product from your up-sell offer (i.e., product replacement happens in the order at checkout).

Usage rules:

• By default, transfer additional parameters for the order in additional_data
• Transfer the additional parameters that you need to use when replacing a product on the checkout page with a product from the up-sell offer in upsell.products.additional_data. Note that each up-sell product has additional parameters inside the up-sell offer. Only the additional parameters that relate to the product selected by the customer are used during replacement.
• If the customer does not agree to the up-sell offer, the default additional parameters are saved into the order (from additional_data)

If the customer agrees to the up-sell offer, the default additional parameters can be replaced or updated with the additional parameters from upsell.products.additional_data of the product selected by the customer. The replacement happens, if the parameter name in upsell.products.additional_data is the same as the parameter name in additional_data. The update takes place if the parameter names differ.