Get short-latency product recommendations over REST. Register type-safe AST rules, evaluate margins in under 5ms, and commit impressions to Postgres.
Your client requests recommendations. The engine matches triggers, calculates expected value margins, passes suppression filters, and registers outcomes.
Retrieve recommendations at checkout and push feedback events back to the outbox ledger.
Post your current cart items and customer segment properties to compile candidates.
The engine responds with candidate details, a template slug, and the unique transaction ID.
Log a feedback event (accepted / declined) to write to the PostgreSQL outbox ledger.
# 1 · request recommendations for cart curl -X POST https://api.softknack.com/upsell/v1/recommendations \ -H "Authorization: Bearer $SK_API_KEY" \ -d '{ "items": [{ "id": "itm_steak", "price": 1200, "qty": 1 }], "customer_segment": "VIP", "session_id": "sess_01J..." }' # 2 · receive recommendation { "suggestion_id": "sg_01J7K...", "recommend_item_id": "itm_wine_bottle", "template": "premium_pairing", "expected_value": 112.50 } # 3 · log when accepted by guest curl -X POST https://api.softknack.com/upsell/v1/suggestions/sg_01J7K.../events \ -H "Authorization: Bearer $SK_API_KEY" \ -d '{ "event": "accepted" }'
// Fetch recommendations from cart context
const res = await fetch("https://api.softknack.com/upsell/v1/recommendations", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SK_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
items: [{ id: "itm_steak", price: 1200, qty: 1 }],
customer_segment: "VIP"
})
});
const data = await res.json();
// Log acceptance to the feedback outbox
await fetch(`https://api.softknack.com/upsell/v1/suggestions/${data.suggestion_id}/events`, {
method: "POST",
headers: { Authorization: `Bearer ${process.env.SK_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({ event: "accepted" })
});
# Fetch and log recommendations using Python
import requests, os
r = requests.post(
"https://api.softknack.com/upsell/v1/recommendations",
headers={"Authorization": f"Bearer {os.environ['SK_API_KEY']}"},
json={"items": [{"id": "itm_steak", "price": 1200, "qty": 1}], "customer_segment": "VIP"}
)
res = r.json()
# Log conversion feedback
requests.post(
f"https://api.softknack.com/upsell/v1/suggestions/{res['suggestion_id']}/events",
headers={"Authorization": f"Bearer {os.environ['SK_API_KEY']}"},
json={"event": "accepted"}
)
Every event is signed and dispatched at-least-once. Stay updated on rules and user conversion events.
AI background worker proposed a new template rule.
A recommendation was evaluated and served to a guest.
The recommendation was accepted and added to the basket.
The recommended offer was dismissed or declined by the guest.
All recommendation data is protected by the same row-level tenant security and write validations that govern the rest of the Softknack suite.
Tenant isolation is compiled in PostgreSQL database policies. Queries cannot leak cross-tenant boundaries.
Cost properties are verified against active catalog values. Rule recommendations must carry verified cost margins.