> For the complete documentation index, see [llms.txt](https://docs.limio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.limio.com/salesforce/setting-up/additional-config/basket-preselection.md).

# Basket Preselection

Preselect offers, quantities and add-ons in the Limio flows from a component of your own on the same page.

#### **LFS version:** requires Limio for Salesforce v14.44 or later

A Lightning web component of your own can preselect offers, quantities and add-ons in the offer selectors of the package. For example, a component that calculates the best offer for a customer can select that offer for the agent.

Your component publishes a message on the Lightning message channel `i42as__Basket_Preselection__c`. The package does not publish offers itself. Thus, nothing changes until your component publishes.

The package subscribes to the channel in the default scope of Lightning Message Service. Thus, your component must be on the same Lightning page as the flow, or in the utility bar. A component in a different console tab does not reach the flow.

{% hint style="warning" %}
Add only components that you trust to the pages of the Limio flows and to the utility bar. The channel is exposed, so any Lightning component in the app can publish to it.

Your component also answers requests on the page of the Limio Manage Subscriptions flow. Before you add it there, make sure that a save offer on Cancel is acceptable. A request does not tell your component which flow sent it, so the component also answers Cancel. On Cancel, a preselected offer changes the cancellation to an order that keeps the customer on that offer.

A message can change the selection of the agent at any time, and the agent gets no notice. The package does not apply the Offer Filtering Rules to a preselected offer. This includes the rules for permission sets and the hidden filters, for example for country or sales channel.
{% endhint %}

## Where the package listens

| Flow                                                           | Component                       | What your component can preselect                                                               |
| -------------------------------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------- |
| Limio Acquisition Journey                                      | Limio Offers Table              | Offers, with a quantity and add-ons for each offer                                              |
| Cancel (Zuora) and Switch                                      | The offer catalog               | One offer, without a quantity or add-ons. On Cancel, this is the offer that saves the customer. |
| Update Subscription, and the Change Offer section of Cancel V2 | Limio Subscription Change Items | One offer, with its quantity and add-ons                                                        |

The Limio Offers Table listens only when its **Order Type** is `new`. The table in the window that opens to change an offer, from Limio Cart Items or Limio Subscription Change Items, does not listen. The other subflows, for example Refund, Renew, Revert Cancel and Manage Add-Ons, do not listen.

The packaged Update Subscription flow hides add-ons. Thus, there your component can preselect only the offer and its quantity. The Change Offer section of Cancel V2 shows add-ons.

In the quote flow **Upsert Limio Quote**, the Limio Offers Table and Limio Subscription Change Items also listen. But the **Generate Limio Quote** and **Edit Limio Quote** actions open it in a new window, not on a Lightning page. Thus, a component on the Opportunity or quote record page does not reach it.

## Message fields

| Field                         | Type         | Meaning                                                                                                                                                                                                                                                                         |
| ----------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`                        | String       | `"request"`: a selector of the package asks for offers. `"answer"`: your reply to a request. No `type`: the message replaces the current selection. The values are case-sensitive. Another value, for example `"Answer"`, has the same effect as no `type`.                     |
| `offers`                      | Array        | Up to 10 offers. Each entry has `offerId` or `offerName`, an optional `quantity`, and optional `addOns`. The package ignores an entry that has neither. When one entry or more has an `offerId` or an `offerName`, the package ignores the top-level `offerId` and `offerName`. |
| `offers[].quantity`           | Whole number | The quantity of the offer. A text value of digits, for example `"2"`, also works.                                                                                                                                                                                               |
| `offers[].addOns`             | Array        | Up to 20 add-ons for each offer. Each entry has `addOnId` or `addOnName`, and an optional `quantity`.                                                                                                                                                                           |
| `offers[].addOns[].addOnId`   | String       | The Limio id of the add-on. When both are set, the package uses `addOnId` and ignores `addOnName`.                                                                                                                                                                              |
| `offers[].addOns[].addOnName` | String       | The Limio name of the add-on. The match ignores the case of the letters.                                                                                                                                                                                                        |
| `offers[].addOns[].quantity`  | Whole number | The quantity of the add-on. A text value of digits also works.                                                                                                                                                                                                                  |
| `offerId`                     | String       | The Limio id of one offer. When both are set, the package uses `offerId` and ignores `offerName`. This rule also applies in each entry of `offers`.                                                                                                                             |
| `offerName`                   | String       | The Limio name of one offer, not its display name. The match ignores the case of the letters.                                                                                                                                                                                   |

`offerId` and `offerName` select one offer only. To send a quantity or add-ons, use `offers`.

A quantity is a whole number, or a text value of digits, for example `"2"`. The package removes spaces before and after the digits. It does not apply a value such as `"2.0"`, `2.5` or `-1`, and the agent sees a warning.

The package ignores a duplicate offer or add-on. It also ignores the entries after the first 10 offers, and after the first 20 add-ons of an offer. It shows no warning for these entries.

A message without a usable `offerId` or `offerName`, for example `{ offers: [] }`, has no effect. Thus, you cannot clear a selection through the channel. The package ignores fields that are not in the table above.

## When to publish

Each selector publishes `{ type: "request" }` when it loads. This occurs each time the agent opens the screen, when the agent selects Change Offer in Cancel V2, and when the **Selected Subscription** of Limio Subscription Change Items changes to another subscription.

Lightning Message Service does not keep messages. A message that you publish before the selector loads is lost. A request that the selector publishes before your component loads is also lost. Thus, your component must do these three steps:

1. Subscribe to the channel.
2. Reply to each request with `type: "answer"`.
3. When your component loads, publish one message with `type: "answer"`.

| Message          | Effect                                                                                                                                                                                                                                                                                                                                             |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type: "answer"` | In the Limio Offers Table and the offer catalog, fills the selector only when nothing is selected. In Limio Subscription Change Items, replaces the current offer only when the item is still the same as on the subscription: the same offer, quantity and add-ons, and no discount. Thus, a change from an earlier message also stops an answer. |
| No `type`        | Replaces the current selection, also a selection that the agent made. You can publish it again at any time while the selector shows.                                                                                                                                                                                                               |

Use one component that publishes to the channel on each page. With several publishers, the result depends on the order of the messages.

## Example

This component answers each request with one offer. It also has a button that replaces the selection of the agent with the same offer. Replace `digital-monthly`, `weekend-print` and the quantity `2` with an offer, an add-on and a quantity from your catalog. Put the three files in the folder `lwc/bestOffer` of your Salesforce DX project, then deploy the folder to your org.

{% code title="bestOffer.js" %}

```javascript
import { LightningElement, wire } from "lwc";
import { MessageContext, publish, subscribe, unsubscribe } from "lightning/messageService";
import BASKET_PRESELECTION from "@salesforce/messageChannel/i42as__Basket_Preselection__c";

const PRESELECTION = {
  offers: [{ offerName: "digital-monthly", quantity: 2, addOns: [{ addOnName: "weekend-print" }] }]
};

export default class BestOffer extends LightningElement {
  @wire(MessageContext) messageContext;
  subscription;

  connectedCallback() {
    this.subscription = subscribe(this.messageContext, BASKET_PRESELECTION, (message) => {
      if (message?.type === "request") this.answer();
    });
    this.answer();
  }

  disconnectedCallback() {
    unsubscribe(this.subscription);
    this.subscription = null;
  }

  answer() {
    publish(this.messageContext, BASKET_PRESELECTION, { type: "answer", ...PRESELECTION });
  }

  handleSelectBestOffer() {
    publish(this.messageContext, BASKET_PRESELECTION, PRESELECTION);
  }
}
```

{% endcode %}

{% code title="bestOffer.html" %}

```html
<template>
  <lightning-button label="Select best offer" onclick={handleSelectBestOffer}></lightning-button>
</template>
```

{% endcode %}

{% code title="bestOffer.js-meta.xml" %}

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
  <apiVersion>66.0</apiVersion>
  <isExposed>true</isExposed>
  <targets>
    <target>lightning__RecordPage</target>
    <target>lightning__AppPage</target>
    <target>lightning__UtilityBar</target>
  </targets>
</LightningComponentBundle>
```

{% endcode %}

Then open the Lightning page that shows the Limio flow in Lightning App Builder. Add the **bestOffer** component to the page, or add it to the utility bar of the app.

In the utility bar, select **Start automatically** for the item. Without this option, the component loads only when the agent opens it. Until then, it does not get the requests of the package and does not answer them.

This example also answers on the page of the Limio Manage Subscriptions flow. There, the packaged Update Subscription flow hides add-ons, so the agent sees a warning for `weekend-print`. On that page, send offers without add-ons.

## How the package applies the message

**Offers**

* The Limio Offers Table and the offer catalog look for the offer in the places below, in this order. If the offer is not in these results, the agent sees a warning.
  1. The offers on the screen. The offer catalog skips this step when **Use new offers table?** is on.
  2. A request to Limio for that id or name.
  3. The first 200 offers of the catalog without filters.
* If the Limio Offers Table finds the offer outside the filters, it adds the offer to the table.
* If more than one offer has the name, the package selects none of them and shows an error.
* The Limio Offers Table selects up to its **Maximum selected offers**. The packaged Limio Acquisition Journey sets this to 1. If more offers match, the table selects the first ones and shows a warning. When the property is empty, the table has no limit.
* The offer catalog and Limio Subscription Change Items take the offers in the order of the message, and use the first offer that they find. They show a warning only when they find none of the offers.
* On Cancel and Switch, the package validates the offer in the same way as a manual selection. Then it confirms the selection and closes the offer catalog.
* On Cancel, a preselected discount offer also sets the effective date to the end of the billing period.
* In Limio Subscription Change Items, the package accepts only the current offer and the offers that the subscription can change to. The [Change Timing](https://docs.limio.com/salesforce/servicing-subscriptions/manage-subscriptions-flow/subflow-update-subscription/change-timing.md) filter does not apply to a preselected offer. A new offer removes a discount or a price override that the agent set.

**Quantities**

* The quantity must be a quantity that the offer allows. The minimum, maximum and increment come from the offer.
* The offer must allow multibuy for a quantity more than 1. In Limio Subscription Change Items, the property **Allow quantity change regardless of offer multibuy** removes this condition. Upsert Limio Quote sets this property. The packaged Update Subscription flow and Cancel V2 do not set it.
* The offer catalog of Cancel and Switch uses the offer only. It ignores the quantity and the add-ons, and shows no warning.
* The package does not apply a quantity that the offer does not allow, and it does not change the quantity to the nearest allowed value. The agent sees a warning.
* In Limio Subscription Change Items, the quantity control must be on. See [Subflow: Update Subscription](https://docs.limio.com/salesforce/servicing-subscriptions/manage-subscriptions-flow/subflow-update-subscription.md).
* If **Read only mode** is on for Limio Cart Items, the package does not apply a quantity. The agent sees a warning.

**Add-ons**

* The package adds the add-on, or changes its quantity. It never removes an add-on.
* If the package cannot find an add-on, it still selects the offer and shows a warning.
* For a new add-on, the minimum, maximum and increment come from the add-on. A quantity more than 1 needs multibuy. When the add-on has no maximum, the maximum is 99.
* For an add-on that is already on the subscription, the package changes the quantity only if Limio allows a quantity change for that add-on.
* If the package cannot apply the quantity of an add-on, the agent sees a warning. The package still adds a new add-on with its default quantity. An add-on that is already there keeps its quantity.
* If the screen hides add-ons, the package does not add them, and the agent sees a warning. These properties hide add-ons:
  * **Add add-on button is hidden** or **Read only mode** on Limio Cart Items.
  * **Hide Add Add-on Button** on Limio Subscription Change Items. The packaged Update Subscription flow sets this property.

## Messages to the agent

When the package cannot apply part of a message, it shows a message to the agent. The text comes from these custom labels:

| Label                                    | Text                                                                                              |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `error_preselected_offer_not_found`      | Not preselected because the offer is not available here: {0}. Select the offer manually.          |
| `error_preselected_offer_ambiguous`      | Not preselected because more than one offer has this name: {0}. Select the offer manually.        |
| `error_preselected_offers_limit`         | Only {0} of the offers sent from the page can be selected here, so the rest were not preselected. |
| `error_preselected_quantity_not_applied` | Quantity not applied because the item does not allow it: {0}. Set the quantity manually.          |
| `error_preselected_addon_not_found`      | Not added because the add-on is not available here: {0}. Add the add-on manually.                 |
| `error_preselected_addon_ambiguous`      | Not added because more than one add-on has this name: {0}. Add the add-on manually.               |
| `error_preselected_addons_not_editable`  | Not added because add-ons cannot be changed on this screen: {0}.                                  |

## Troubleshooting

| Problem                                                                  | Cause and fix                                                                                                                                                                                                                                                                  |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Nothing changes                                                          | Make sure that your component is on the same Lightning page as the flow, or in the utility bar. Make sure that it answers each request, and publishes an answer when it loads. Make sure that the screen listens, see [Where the package listens](#where-the-package-listens). |
| An answer has no effect                                                  | The selector already has a selection, or the agent changed the item. To replace the selection, publish without `type`.                                                                                                                                                         |
| A message replaces the selection of the agent                            | The value of `type` is not in lower case. The package reads `"Answer"` as no `type`.                                                                                                                                                                                           |
| On Update Subscription, the offer does not change                        | The package applies a message only after Limio opens the change basket. If this request to Limio fails, the package applies nothing.                                                                                                                                           |
| The agent sees "Not preselected because the offer is not available here" | The offer is not in the places that the package searches. See [How the package applies the message](#how-the-package-applies-the-message). If the request to Limio failed, the console of the browser shows `Error looking up a preselected offer:`.                           |
| Nothing changes and the agent sees no warning                            | Open the console of the browser. An unexpected error writes `Error preselecting offer:` and the error.                                                                                                                                                                         |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.limio.com/salesforce/setting-up/additional-config/basket-preselection.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
