Skip to main content
This playbook is for commerce applications that want assistant answers inside order, product, or support flows. Typical examples:
  • Product availability questions
  • Delivery policy questions
  • Return and refund policy questions
  • Warranty and care instructions
  • Checkout help that relies on approved public content
Use your own backend for private account checks, payment decisions, refund approvals, and order mutations. Uppzy should receive the user question and the approved reference content needed to answer it.

​
Flow

  1. Sync approved commerce content into Uppzy
  2. Generate a stable session_id for the shopper or support thread
  3. Send the user question to the sync chat endpoint
  4. Render the answer in your application
  5. Submit feedback when the user rates the response
  6. Monitor sessions and statistics during rollout

​
Recommended content model

Start with documents that are already approved for customer-facing use:
  • Return policy
  • Shipping policy
  • Warranty policy
  • Product care instructions
  • Top FAQs
  • Store hours or support hours
For direct FAQs, prefer Q&A documents. 
curl --silent --show-error \
  --request POST \
  --url "$UPPZY_BASE_URL/m2m/sites/$UPPZY_SITE_ID/documents/qa" \
  --header "X-API-Key: $UPPZY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "title": "Return Window FAQ",
    "question": "How long do customers have to return an item?",
    "answer": "Customers can start a return within the return window published in the store policy.",
    "category": "returns"
  }'

​
Session strategy

Use a stable opaque identifier. Avoid raw email addresses or full personal identifiers in session_id. Good patterns:
  • shopper_7f3a9c
  • support_thread_48291
  • checkout_session_a18b2
Avoid:
  • Raw email addresses
  • Payment identifiers
  • Full address or phone data
  • Anything that would expose private customer data in logs

​
Server-side chat route

This example shows a backend route that sends a shopper question to Uppzy. 
import { uppzy } from "./uppzy-client.js";

const SITE_ID = process.env.UPPZY_SITE_ID;

export async function answerCommerceQuestion(req, res) {
  const { shopperId, message, locale } = req.body;

  if (!shopperId || !message) {
    return res.status(400).json({ error: "shopperId and message are required" });
  }

  const sessionId = `shopper_${shopperId}`;

  const answer = await uppzy(`/m2m/sites/${SITE_ID}/chat`, {
    method: "POST",
    body: {
      session_id: sessionId,
      message,
      ui_locale: locale || "en",
      response_language: locale || "en",
    },
  });

  return res.json({
    session_id: answer.session_id,
    request_id: answer.request_id,
    answer: answer.answer,
    confidence_level: answer.confidence_level,
  });
}

​
Feedback route

Collect feedback from the same application flow that displayed the answer. 
import { uppzy } from "./uppzy-client.js";

const SITE_ID = process.env.UPPZY_SITE_ID;

export async function rateCommerceAnswer(req, res) {
  const { sessionId, requestId, rating } = req.body;

  if (!["good", "bad"].includes(rating)) {
    return res.status(400).json({ error: "rating must be good or bad" });
  }

  await uppzy(`/m2m/sites/${SITE_ID}/chat/feedback`, {
    method: "POST",
    body: {
      session_id: sessionId,
      request_id: requestId,
      feedback: rating,
    },
  });

  return res.status(204).end();
}

​
Rollout checklist

  • Start with policy and FAQ content only
  • Keep refund approval, payment changes, and order edits inside your own backend
  • Use opaque session IDs
  • Add a visible support fallback for low-confidence answers
  • Review bad feedback and unanswered questions after launch
  • Track statistics before increasing traffic