Configuration

Knowledge Base: writing FAQs the AI can use

How to phrase FAQ entries so the AI grounds its answers in your policies, not its priors.

Last updated

The knowledge base is where you teach OrderWise the answers that aren't in Shopify's order data — shipping policies, return windows, sizing guides, restocking fees, gift-card rules. The AI uses these entries as ground truth when a customer asks anything that isn't a live order lookup.

What makes a good FAQ entry

Two things matter: the question and the answer.

Question phrasing should match how customers actually ask, not how you internally categorize the policy. "Return shipping costs" is a good internal label and a bad question. "Who pays for return shipping?" is the question a customer would type. The retrieval index does fuzzy matching, but the closer the entry phrasing is to natural language, the more reliable the match.

Answers should be specific and contain the exact numbers and conditions. Don't write "We accept returns within our standard return window." Write "We accept returns within 30 days of delivery. Items must be unworn and in original packaging. The customer pays return shipping unless the item arrived damaged." The AI doesn't paraphrase well across ambiguity — give it the facts directly.

Examples that work

Good:

  • Q: How long does shipping take to Germany?
  • A: Standard shipping to Germany is 2-4 business days via DHL. Express is next-day if ordered before 14:00 CET. Shipping is free for orders over 50 EUR; otherwise 4.99 EUR.

Less good:

  • Q: Shipping
  • A: We ship via reliable carriers. Times vary by region.

The first version gives the AI everything it needs to answer a follow-up ("when will mine arrive?") without making anything up. The second forces the AI to hedge or ask clarifying questions the customer didn't want.

Locales

You can author a separate entry per locale, or write the entry in your primary language and let OrderWise translate at runtime. The locale-specific version is always preferred when both exist — translation is the fallback for languages you haven't authored manually.

When to use metaobjects instead

If you're already maintaining a customer-service knowledge base inside Shopify (via the orderwise_faq metaobject), point OrderWise at that metaobject definition under Settings → Knowledge Base → Metaobjects. Edits in Shopify push to OrderWise automatically via the metaobjects webhook.