1. Customers Events
Salla Platform Docs
  • Welcome 👋
  • What are App Functions?
  • Get Started
  • Supported Events
  • Testing
  • Responses
  • NodeJs Support
  • Command Line Interface (CLI)
  • Merchants Events
    • Invoice Events
    • Shipping Zone Events
    • Category Events
    • Special Offer Events
    • Customer Events
    • Store Branch Events
    • Shipping Company Events
    • Review Events
    • Shipment Events
    • Cart Events
    • Brand Events
    • Communication Events
    • Order Events
  • Customers Events
    • Checkout Recommendations
    • Account Events
    • Product Events
    • Promotion & Coupon Events
    • Wishlist Events
    • Cart & Checkout Events
Merchant
Merchant
  • Merchant API
  • Embedded SDK
  • Salla OAuth 2.0
Storefront
Storefront
  • Twilight (React)
  • Twilight SDK
  • Web Components (Deprecated)
  • Ecommerce Events
  • Component Bundle
  • Checkout APIs
  • Twilight Engine (Deprecated)
  • Change Log
App Functions
Partner APIs
Partner APIs
  • App API
  • Shipments & Fulfillment APIs
  • Salla AWB
  • Recurring Payments API
  • Billing System Salla partners
  • Communication Apps
Dev Tools
Dev Tools
  • Partners Agent Kit
  • Salla Apps Playbook
  • Salla CLI
Merchant
Merchant
  • Merchant API
  • Embedded SDK
  • Salla OAuth 2.0
Storefront
Storefront
  • Twilight (React)
  • Twilight SDK
  • Web Components (Deprecated)
  • Ecommerce Events
  • Component Bundle
  • Checkout APIs
  • Twilight Engine (Deprecated)
  • Change Log
App Functions
Partner APIs
Partner APIs
  • App API
  • Shipments & Fulfillment APIs
  • Salla AWB
  • Recurring Payments API
  • Billing System Salla partners
  • Communication Apps
Dev Tools
Dev Tools
  • Partners Agent Kit
  • Salla Apps Playbook
  • Salla CLI
Salla - Opensource
Salla - Developers Community
  1. Customers Events

Checkout Recommendations

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#

FieldTypeNotes
payload.merchantnumberStore ID
payload.data.cart_idstringA 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.currencystringCart currency
payload.data.country_codestringISO code of the cart's market
payload.data.languagestringStorefront language, for locale-aware ranking
payload.data.total{ amount, currency }Cart total
payload.data.subtotal{ amount, currency }Cart subtotal
payload.data.items[]arrayWhat the shopper is about to buy (up to 100 lines)
payload.data.items[].product_idnumberSalla product ID
payload.data.items[].quantitynumberQuantity in the cart
payload.data.items[].price{ amount, currency }Per-item price
merchant.idnumber | stringStore ID, as on every other trigger
settingsobjectYour 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#

RuleBehaviour
Positive integers only"123" (string), 0, negatives, floats and null are each discarded
Duplicates removedThe first occurrence wins
Up to 10 acceptedThe first 10 surviving IDs are kept, in your order
At most 4 renderedRanking order is what matters - put your best recommendation first
Must belong to this storeForeign 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?

Related Events#

Cart & Checkout Events - the asynchronous customer events fired around the same checkout
Product Events - product views and clicks
Responses - the Resp contract in full
Modified at 2026-11-16 13:37:55
Previous
Order Events
Next
Account Events