This model defines the structure for the event Salla fires to ask your app which products to recommend to a shopper on the checkout page. Salla renders the products you return as a cross-sell block with one-tap add-to-cart.Available Events#
checkout.recommendations - Salla asks your app which products to recommend on the checkout page
Event Type#
Synchronous Action - the shopper is waiting. Salla stops waiting after 2 seconds.Unlike other synchronous actions, a failure here never blocks anything. A timeout, a non-2xx response, or a response without a usable product_ids array simply means the cross-sell block does not render. The shopper's checkout continues unaffected.
How Your App Gets Called#
Your function runs only when the merchant has explicitly selected your app as their recommendation source, under Settings > Marketing > Smart recommendations. The default source is Salla's own AI recommender.To be selectable, your app must be installed on the store and have a live checkout.recommendations function.Common Use Cases#
Recommend complementary products ("frequently bought together")
Up-sell a larger size or a premium variant of what is in the cart
Surface a bundle or volume discount the cart nearly qualifies for
Promote best sellers from your own ranking model
Recommend from an external personalisation engine the merchant already pays for
Context Object#
{
"payload": {
"merchant": 101,
"data": {
"cart_id": "4610288113929283001",
"currency": "SAR",
"country_code": "SA",
"language": "ar",
"total": { "amount": 198.00, "currency": "SAR" },
"subtotal": { "amount": 172.17, "currency": "SAR" },
"items": [
{
"product_id": 5001,
"quantity": 2,
"price": { "amount": 99.00, "currency": "SAR" }
}
]
}
},
"merchant": { "id": 101 },
"settings": {}
}
Fields#
| Field | Type | Notes |
|---|
payload.merchant | number | Store ID |
payload.data.cart_id | string | A decimal string, not a number - cart IDs exceed 2^53 and lose precision as numbers. Do not pass it through parseInt or Number. |
payload.data.currency | string | Cart currency |
payload.data.country_code | string | ISO code of the cart's market |
payload.data.language | string | Storefront language, for locale-aware ranking |
payload.data.total | { amount, currency } | Cart total |
payload.data.subtotal | { amount, currency } | Cart subtotal |
payload.data.items[] | array | What the shopper is about to buy (up to 100 lines) |
payload.data.items[].product_id | number | Salla product ID |
payload.data.items[].quantity | number | Quantity in the cart |
payload.data.items[].price | { amount, currency } | Per-item price |
merchant.id | number | string | Store ID, as on every other trigger |
settings | object | Your app's merchant-configured settings |
Money is always { amount, currency }, never a bare number - including the per-item price.No shopper identity reaches your function. There is no customer, no coupon and no checkout_url in the payload, by design.
Response#
Return Salla product IDs and nothing else:product_ids Rules#
| Rule | Behaviour |
|---|
| Positive integers only | "123" (string), 0, negatives, floats and null are each discarded |
| Duplicates removed | The first occurrence wins |
| Up to 10 accepted | The first 10 surviving IDs are kept, in your order |
| At most 4 rendered | Ranking order is what matters - put your best recommendation first |
| Must belong to this store | Foreign IDs are dropped during rendering |
What Salla Ignores#
Salla renders every card from its own catalog and prices it through its own offers engine. Any title, price, image, discount, label, colour or layout your app returns is ignored. product_ids is the entire contract.Why a Product You Returned May Not Appear#
Your IDs pass an eligibility filter before rendering. An ID is dropped when the product:does not belong to this store
is already in the shopper's cart
is hidden, out of stock, or unavailable
requires the shopper to choose something - it has options or variants, a required note, a file upload, or custom fields. The block is one-tap add-to-cart, so anything needing input cannot be offered.
is a donation, financial-support, booking or order-option product
is an advanced bundle, or shows its price as a dash
needs shipping while the cart has no shipping step
This is why a correct, well-ranked response can still render nothing. On a catalog where most products carry size or colour options, few IDs survive - check your recommendations for product options first if the block is not appearing.A booking cart cannot accept a regular product, so no recommendations are shown on one at all.
Example Implementation#
Recommend From Your Own Ranking Model#
Up-Sell Toward a Free-Shipping Threshold#
Testing#
1
Build against the mock payload
Use the Preview panel in the Partners Portal - it serves a mock cart payload, so you can build against the contract without a live checkout.
2
Install your app
Install the app on a demo store.
3
Select your app as the source
In the store dashboard, go to Settings > Marketing > Smart recommendations and select your app instead of Salla AI.
4
Open a real checkout
Add products to the cart and open the checkout page.
5
If nothing renders
Work down this list before suspecting the trigger: are your IDs numbers, not strings? Do the products have options or variants (those can never be offered)? Are they already in the cart? Did your function answer within 2 seconds?