Merchant operating tutorials

Read workspace health before making changes

Outcome: You can separate setup gaps, operational failures, and directional performance signals.

Why this sequence: A readiness check prevents spending time optimizing a metric that is empty because the catalog is stale, the assistant is not installed or an essential service is unavailable. Work from a current source record to the headline, rather than treating every alert as the same kind of failure.

When not to use it: Do not use a short, partial reporting period to decide that an agent increased profit, or dismiss a readiness warning as a way to fix the underlying integration.

Prerequisites

• A store membership
• A known reporting timezone and currency
• Access to the commerce platform for reconciliation

Procedure

1. Open the store root and confirm it redirects to Overview for the intended store ID.
2. Read sync status and launch-readiness findings before reading revenue or conversion cards.
3. Check the selected period, KPI definition, attribution note, and any Pro-only prediction panels.
4. Open the suggested next action in its owning workspace; do not resolve an alert by dismissing it elsewhere.

Completion evidence

• Representative KPI records reconcile with their source
• Readiness findings have owners
• The next action is based on current evidence

Synthetic worked example

A fictional outdoor store has finished account setup but Overview shows products without usable answers and no attributed orders.

1. Confirm the selected store and open Store Details. Record the last completed sync and current product count; keep those timestamps with your test notes.
2. Open Products and inspect a test jacket's active status, variants, price and stock. Compare it with the commerce source, then check Imports for completed indexing.
3. Open Widget Designer, confirm the installation path and audience, and ask a controlled storefront question that should retrieve that jacket. Ask an unsupported compatibility question as a negative case.
4. Return to Overview and inspect the same reporting period. Follow any remaining readiness action into its owning screen rather than changing the plan or AI Budget to chase a zero.

Expected result: A completed data path and a relevant sourced answer establish a usable test case. A controlled query does not establish sales lift; zero attributed orders can be normal before a qualifying purchase exists.

Limitations and consequential settings

• Connection, source sync, search indexing and storefront installation are separate readiness conditions.
• AI-influenced revenue credits the documented qualifying interaction; it is not net-new revenue or profit. Predictions and suggestions require source review.
• Production credentials, provider availability, destination approvals and real-user performance require environment-specific checks.

Troubleshoot this workflow

Products exist but answers cannot find them

Compare active status and source fields, then inspect indexing completion and provider availability. A completed catalog import alone does not prove retrieval is ready.

Revenue or usage appears inconsistent

Record currency, timezone, dates, filters, native order state and provider rail. Compare one known order or usage period before changing settings.

Related next steps

• Read connection and job health
• Understand the Overview metrics
• Investigate a remaining failure

Page-by-page checklist

Triage a shopper issue from queue to resolution

Outcome: A human can find, understand, own, respond to, and close a supported shopper case without losing context.

Why this sequence: A thread contains shopper context, while a ticket supplies durable ownership and status. Using both deliberately reduces the risk of replying twice, exposing another shopper's order or marking a request complete before the actual operation finishes.

When not to use it: Do not use ticket status as evidence that money moved, shipment details changed or a message was delivered. Do not use an unverified email typed into chat as permission to reveal protected order information.

Prerequisites

• Inbox capability
• A connected reply channel where external replies are expected
• An agreed assignment and escalation policy

Procedure

1. Open Inbox. Use Conversations for channel threads or choose Tickets for support cases; filter by needs-reply, assignment, priority and due-time risk.
2. Open the ticket or conversation and read the complete timeline, shopper identity, citations, tool results, and internal notes.
3. Assign an owner. Use a canned reply only as an editable starting point, then send through the supported channel.
4. Record feedback on an AI reply when it was good, incomplete, wrong, or should have handed off.
5. Update status only after the external provider result and required follow-up are clear.

Completion evidence

• The case has an owner and correct status
• Provider delivery or failure is visible
• Any AI-quality issue has actionable feedback
• The ticket and conversation agree

Synthetic worked example

A fictional WooCommerce shopper asks for a refund on an unshipped order and needs a human decision.

1. Open Inbox → Tickets and locate the controlled case. Read the linked conversation and source order, including the shopper's verified identity and the actual request.
2. Assign an accountable teammate and set priority according to the documented workflow. Review any internal notes before deciding how the request should be handled.
3. Check the platform action boundary: WooCommerce cancellation, item-edit and refund tools route to a ticket rather than executing those operations. A human uses the store's approved operation and records the result.
4. Draft a factual reply, using a canned reply only as an editable starting point. Send through the configured channel and inspect acceptance or failure; update case status after the required work is complete.
5. Reload the ticket and source thread. If the AI gave a wrong policy answer, record message feedback and route the correction to Knowledge or AI Improver.

Expected result: The case has an owner, the source platform reflects any separately approved operation, and the reply and ticket state agree. An internal note remains internal; a queued message is not proof of delivery.

Limitations and consequential settings

• Connected reply-channel permissions and provider session rules can limit replies. External helpdesk synchronization must be verified in both directions.
• SLA targets count round-the-clock minutes and are set for new tickets. They flag due times; they do not create staffing, auto-close cases or promise a response from Zubby support.
• Address changes have different defaults and platform support from money-moving actions; follow AI Setup rather than treating all order actions alike.

Troubleshoot this workflow

The case is not in the queue

Check Conversations versus Tickets, status and assignment filters, the selected store, and the source event. Legacy /tickets links redirect into the current Tickets view.

A local reply exists but the shopper did not see it

Inspect channel connection, provider acceptance/error and the external thread. If the outcome is uncertain, establish whether the send executed before submitting it again.

A target is already breached

Compare ticket creation time and its saved due time. Settings changes affect newly created tickets; nights, holidays and weekends do not pause the clock.

Related next steps

• Ticket states and human replies
• Handoff and helpdesk setup
• Choose staffable internal targets

Page-by-page checklist

Connect, synchronize, and ground the AI

Outcome: Products and authoritative merchant knowledge are synchronized, searchable, and sample-verified.

Why this sequence: The assistant can only ground a useful answer in the facts and searchable documents available to the store. Fixing source ownership, freshness and indexing first is more reliable than using a prompt to compensate for an incorrect price or missing policy.

When not to use it: Do not publish generated product claims without evidence, repeat overlapping imports to clear a queued status, or treat a catalog completeness check as proof of public Google markup or rich-result eligibility.

Prerequisites

• Catalog capability
• A managed connection or a custom-store ingestion integration
• Required platform scopes or a Pro store-scoped API write key
• No active catalog-service incident

Procedure

1. For a new managed connection, complete WooCommerce plugin pairing. New Shopify connections are coming soon; existing authorized Shopify stores can inspect their supported sync. Custom/API stores use the Pro public catalog ingestion API.
2. Run the smallest appropriate import and monitor its real job state in Imports and Store Details.
3. Compare sample products, variants, prices, inventory, categories, and orders with the source platform.
4. Open failed or incomplete products and fix source data or product-specific AI tuning where appropriate.
5. Add policies, FAQs, and locked facts to Knowledge; approve only grounded suggestions.
6. Wait for embedding completion, then test product discovery and policy questions and inspect citations.

Completion evidence

• Import and search-indexing status completed
• Counts and representative records reconcile
• Search finds expected products
• Policy answers cite approved sources
• Merchant-visible failure states were tested

Synthetic worked example

A fictional custom store needs to ingest one test product and a returns policy before testing discovery.

1. With Pro API access, create the minimum required write key in API Keys and keep it on the integration server. Managed Shopify and WooCommerce stores should use their connector's import path instead.
2. Send the synthetic catalog payload shown below to the documented catalog ingestion endpoint using a store-scoped bearer key. Reuse stable external IDs on updates and inspect the actual response for validation or per-record failures.
3. Open Products, locate the test product and compare variants, currency assumptions, availability and source URL. Wait for embedding/indexing work to complete before testing search.
4. Add the approved returns material through Knowledge or FAQ. Resolve source conflicts, approve only supported facts and wait for the document's search-ready state.
5. Ask for the test product using two phrasings, an unavailable variant and an unsupported return exception. Check source citations and expected handoff rather than only whether any answer appeared.

Synthetic body for POST /api/public/v1/catalog, sent from your integration server with a write-scoped bearer key. This example stores one product; it does not place an order. Replace the example domain and values with verified data in a test store. Review the API reference before integrating; omitted fields can have update semantics.

{
  "products": [
    {
      "externalId": "test-jacket-001",
      "title": "Test rain jacket",
      "description": "Synthetic catalog item for integration verification.",
      "status": "active",
      "url": "https://store.example/products/test-rain-jacket",
      "variants": [
        {
          "externalId": "test-jacket-medium",
          "title": "Medium",
          "sku": "TEST-JACKET-M",
          "price": "80.00",
          "inventory": 5,
          "inventoryTracked": true
        }
      ]
    }
  ]
}

Expected result: The product is stored under the same external ID, search finds the appropriate variant after indexing, and the policy answer cites approved material. Ingestion success does not guarantee background embedding success.

Limitations and consequential settings

• Custom-store freshness depends on the last push. Managed imports, historical orders and knowledge imports have separate scopes; follow the specific connector guide.
• Platform-owned taxonomy and product fields may be overwritten by the next sync. Change the authoritative source or the supported AI tuning control as appropriate.
• Metafields are default-deny. Allow only shopper-safe keys; do not make cost or supplier namespaces public to solve a retrieval problem.
• Catalog structured data and generated enrichment are stored inputs. Validate rendered storefront markup and every substantive claim independently.

Troubleshoot this workflow

400 on ingestion

Compare the response details with the current API schema: stable externalId, non-empty title, correct money values, valid URLs and supported batch limits. Do not include production secrets in a support example.

Records are stored but the shopper answer is stale

Check indexing status, duplicate/conflicting knowledge and the actual synced version. A recurring import can reintroduce a removed source document.

Import stalls or some records fail

Record job/request ID, source type and safe error. Compare completed and failed counts, Store Details and Notifications before one controlled retry.

Related next steps

• Exact ingestion contracts and failure responses
• Publish approved searchable knowledge
• Import scope and source ownership

Page-by-page checklist

Launch a controlled recovery or campaign workflow

Outcome: One eligible shopper can enter, receive, exit, and be measured through a consent-aware workflow.

Why this sequence: A lifecycle workflow is only useful if the right person enters it, messages stop when they should, and the channel can deliver. Explicit exits and suppression prevent a technically successful send from becoming an unwanted message after purchase.

When not to use it: Do not activate on an unverified audience or claim stock reservation, a price hold or a deadline that the store does not implement. Do not queue a broadcast expecting to approve every recipient's AI text afterward.

Prerequisites

• Recovery capability
• Required Growth or channel entitlement
• No active recovery-service incident
• Connected sending channel
• Consent and suppression rules

Procedure

1. Choose the specific workflow: Cart Rescue while the shopper is present; Recovery after abandonment; Journeys for lifecycle steps; Broadcasts for a one-off send; Promo bars for storefront display; Social for external posts.
2. Define a narrow audience, trigger, message, schedule, exit, suppression, and success event.
3. Review available copy, links, real offer terms, sender identity and channel policy. In Broadcasts, review Segment, Channel and Brief before Queue broadcast; email/SMS copy is generated after queueing, while WhatsApp uses an approved template.
4. Run a controlled eligible case and a non-eligible case; inspect the merchant-visible workflow and delivery state.
5. Trace delivery, click, order, exit, and failure behavior, then compare with the documented attribution rule.
6. Expand traffic only after complaints, unsubscribes, provider failures, and commerce outcomes are acceptable.

Completion evidence

• Eligibility and suppression work
• Provider acceptance and a controlled received example are checked separately
• Failures are investigated through the owning workflow; retry behavior is not assumed
• Attribution is reported as directional
• A rollback or pause path is known

Synthetic worked example

A fictional test store wants a single helpful cart-abandonment email, with no invented urgency or discount.

1. Confirm recovery access, the applicable plan and a connected sender. Use controlled profiles authorized to receive tests; include one eligible profile, one unsubscribed profile and one that purchases before sending.
2. In Journeys, create a Cart abandoned workflow and inspect its actual steps. Give it a clear name, review the delay, channel, audience and exit behavior, and save before activation.
3. Write factual instructions: offer help, include the supported cart link, say price and availability may change, and preserve unsubscribe handling. Use an actual expiring offer only when its configured terms justify the expiry.
4. Activate only in the controlled environment. Trace abandonment, enrollment, due time, suppression and provider acceptance; inspect the received message and confirm purchase exits separately.
5. For a one-off campaign instead, use Broadcasts → Segment, Channel and Brief → Queue broadcast, or Launch draft for a saved Campaign Composer draft. Membership is resolved when the worker processes it, with consent checks; a preview count is not a fixed recipient list.

Expected result: The eligible test can be traced through its send path, and opt-out or purchase cases are excluded at the relevant checks. An order after a message is an association until an appropriate no-send experiment isolates email effect.

Limitations and consequential settings

• Growth gates journeys and broadcasts; SMS/WhatsApp require Pro and configured channels. WhatsApp outside its session window requires an approved template.
• Custom-segment support is destination-specific. Broadcast and Campaign Composer support does not automatically establish widget-rule or every journey-trigger support.
• Quiet hours use configured timezone behavior, not an assumed per-recipient timezone. SMS length depends on encoding, links and opt-out text as well as character count.
• Queue retries, provider retries and merchant outbound-webhook delivery are different systems. Outbound event notifications are best-effort without automatic retries.

Troubleshoot this workflow

No enrollment

Inspect source event availability, identity, trigger, audience, active state and plan before editing message text. Delivery events depend on the source platform and tracking data.

Enrolled but not sent

Check due time, quiet hours, current consent, purchase exits, caps and sender/provider state. A paused or future step differs from a failed send.

Unexpected recipient or content

Compare the resolved segment and source profile with the brief. Pause expansion and review received examples; Content Studio's selected variant does not lock per-recipient broadcast wording.

Related next steps

• Triggers, step delays and exits
• Direct sends and draft launch behavior
• In-session rescue versus later recovery

Page-by-page checklist

Investigate a metric and reconcile it to source records

Outcome: A merchant can explain what a metric includes, find its underlying records, and avoid unsupported causal claims.

Why this sequence: A number becomes useful when its units, records and credit rule are known. Reconciliation finds missing or duplicate events, while a suitable experiment addresses whether an intervention changed behavior.

When not to use it: Do not compare a filtered attributed numerator with a denominator filtered to the same AI orders, equate revenue with contribution profit, or use a chat holdout as evidence of recovery-email lift.

Prerequisites

• Analytics capability
• Known timezone, currency, and date range
• Commerce access for order reconciliation

Procedure

1. Select a complete period and record the metric definition, attribution window, and exclusions.
2. Use Funnel or Cohorts to identify a question, not to declare a cause.
3. Open representative shoppers and orders and compare platform IDs, amounts, statuses, and event timing.
4. Use Segments to preview the affected audience and review boundary cases.
5. Generate the smallest necessary report and verify its headers, row count, and samples.
6. Record uncertainty. Use a suitable controlled design when a causal answer is required; the built-in opening-message test, chat holdout and a recovery-email no-send control answer different questions.

Completion evidence

• Samples reconcile with commerce data
• Timezone and currency are explicit
• Incomplete periods are excluded or labeled
• Attribution is not presented as incremental lift
• Exports are handled securely

Synthetic worked example

A fictional order contains the recommended jacket and an unrelated accessory. The dashboard gives the qualifying AI interaction full-order credit.

1. Open Orders with an unfiltered comparison period. Record total revenue, included statuses, currency and timezone before filtering to AI-influenced orders.
2. Open the test order and its linked conversation. Check that a purchased line matches the recommended product and the interaction falls within the documented attribution window.
3. Compare the platform order ID, amount, refunds, item quantities and timestamp with the source store. Full-order credit includes the accessory; document that possible over-credit rather than calling the figure a floor.
4. Use Analytics, Funnel or Cohorts for the next descriptive question. In Reports, download a supported CSV and check its fixed window, headers and sample IDs; the public API is not a general historical reports service.
5. When comparing with GA4 or an ad platform, reconcile transaction coverage first, then record each report's attribution model, identity and windows. Different credit allocation can be expected even when raw orders agree.

Expected result: You can explain why the order is attributed, which value received credit and which costs are absent. The example establishes a calculation trace, not a measured increase in revenue or profit.

Limitations and consequential settings

• Chat attribution, recovery-associated revenue, randomized lift and profit answer different questions and must stay separately labeled.
• Costs, fees, refunds and tracking coverage affect profit. Predictive lifetime value must not be inferred from realized shopper spend or cohort history.
• Current partial periods, mature versus young cohorts and changing traffic mix can distort comparisons. Internal benchmarks need population and sample context.
• Built-in experiment confidence labels and minimum samples do not eliminate repeated-check or multiple-comparison concerns.

Troubleshoot this workflow

Revenue differs from the store

Compare order IDs, currency, net/refund state, source timestamps, window and filters before attributing the discrepancy to a model difference.

A funnel stage is empty

Replay a controlled event path and check source coverage and identity continuity. Missing instrumentation is not evidence shoppers abandoned at that step.

A report omits an old order

Check the export's documented fixed window and source ingestion. Do not assume an undocumented public orders-read endpoint exists to bypass it.

Related next steps

• Order evidence and filtering
• Attribution definitions and limitations
• Costs and profit calculations
• Supported exports

Page-by-page checklist

Correct an AI-quality problem with grounded evidence

Outcome: A weak answer becomes a specific, reviewable correction and a repeatable verification case.

Why this sequence: A correction should address the source of the mistake and include a regression case. Otherwise a tone change can hide a knowledge error, or a plausible generated answer can become a new unsupported policy.

When not to use it: Do not approve a partial speculative draft to increase coverage, copy personal information into general knowledge, or use a feedback badge as proof the underlying problem is fixed.

Prerequisites

• Training capability
• The original conversation or feedback signal
• Authoritative product, policy, or operational evidence
• Completed search indexing for knowledge changes

Procedure

1. Start in AI Quality, Knowledge Gaps, Reviews & Feedback, or AI Improver and open the original conversation.
2. Classify the root cause: missing knowledge, stale fact, catalog error, bad ranking, tone, rule, tool behavior, or missing handoff.
3. Make the correction in the owning surface: Knowledge, Locked Facts, FAQ, Product Tuning, Brand Voice, Rules, or AI Setup.
4. Treat AI-suggested enrichment or draft answers as untrusted drafts until compared with authoritative sources and approved.
5. Wait until the knowledge or indexing status is ready, then replay the original question plus paraphrase, counterexample, and handoff cases.

Completion evidence

• The root cause and owner are documented
• The correction is approved and persisted
• Retrieval or behavior is tested after background work
• The fix does not create a nearby regression

Synthetic worked example

A fictional assistant says returns are free everywhere, but the approved policy limits prepaid returns to one region.

1. Open Reviews → AI feedback or Knowledge Gaps and read the original conversation. Compare the response and citation with the current approved return policy.
2. Mark the unsupported answer appropriately and identify its source: stale Knowledge, an incomplete FAQ, a conflicting Locked Fact or an objection rule.
3. Correct the owning source to include the region and exceptions. In AI Improver, review a suggested draft against that policy before accepting; reject invented terms.
4. Wait for approved knowledge to finish indexing, then test a supported region, an excluded region, an unspecified destination and a paraphrase. Inspect sources as well as the final answer.
5. Open the original worklist again and record what changed. If the original source still imports the stale policy, fix that refresh path rather than deleting it repeatedly.

Expected result: Supported cases use the corrected policy, missing destination information causes clarification, and unsupported exceptions hand off. The test log records the exact source and residual failures without claiming universal accuracy.

Limitations and consequential settings

• Reviews is a hub: AI feedback, Product reviews and Moderation queue have different permission and source requirements.
• Knowledge save, approval and completed embeddings are separate. Product tuning, brand voice and tool boundaries can require different verification paths.
• An AI confidence signal is not a calibrated accuracy rate. Locked Facts and source grounding reduce risk but do not guarantee no mistakes.

Troubleshoot this workflow

The corrected answer is not retrieved

Check approval/indexing state, conflicting facts and the actual document version. Confirm the original importing source did not overwrite the correction.

Nearby questions regress

Narrow a broad rule or source statement, retain exceptions and retest negative cases. Do not solve an uncertain policy by adding more unsupported prose.

Related next steps

• Approval and gap resolution
• Source lifecycle and indexing
• Choose the correct review tab

Page-by-page checklist

Configure and validate a growth feature

Outcome: A growth tool changes only the intended shopper experience and has a measurable, reversible rollout.

Why this sequence: A useful growth change serves a specific shopper task and leaves non-target behavior intact. Define the intended match and the guardrail before changing a ranking weight, reward, theme or message.

When not to use it: Do not test every variable at once, infer exposure probability from ranking weight, advertise inactive referral rewards or use a scripted example as evidence of a customer's result.

Prerequisites

• The route's growth or widget capability
• Any route-specific entitlement
• A baseline and primary metric
• A controlled test audience

Procedure

1. Choose the owning feature: experiment, recommendation, playbook, loyalty, affiliate, widget, content, reviews, review queue, or rule.
2. Review source data and define the intended audience, trigger, action, guardrail, and rollback.
3. Preview or test the feature with positive, negative, boundary, out-of-stock, mobile, and accessibility cases as applicable.
4. For generated content or AI corrections, fact-check and explicitly approve; for external actions, verify provider-side state.
5. Use Rule Effectiveness or A/B Tests where available, but require adequate samples and guardrail review before promotion.

Completion evidence

• The target and non-target experiences are verified
• Plan and role gates behave correctly
• External state is proven where relevant
• Rollback is available
• Results are not overstated

Synthetic worked example

A fictional store wants a rain-jacket query to find a suitable product without promoting it in unrelated conversations.

1. Check Products for accurate material, stock and compatibility facts. Open Rules & Voice → Merchandising rules and define a narrow relevant scope for the intended product.
2. Apply one supported adjustment and test matching, near-match, unrelated and out-of-stock queries. Record recommended products and why they fit; do not interpret a 2× score as twice the display probability.
3. If testing a greeting instead, use AI Setup's Opening message A/B test and compare supported variants on add-to-cart with purchases as a guardrail. Keep merchandising and theme stable during that test.
4. For Widget Designer, save and test the actual launcher or inline placement on desktop and mobile, including keyboard close and audience suppression. Preview alone does not validate theme integration.
5. For loyalty, test earning, one redemption, code delivery and checkout separately. For Product-Finder Quizzes, validate every answer-to-filter mapping and a no-match case before publishing.

Expected result: The intended shopper task works and control cases remain sensible. A stored rule, published quiz or points deduction establishes only its own step; recommendation quality, checkout reward application and measured effect need separate evidence.

Limitations and consequential settings

• Growth gates the relevant tools; premium themes, review lookups, quizzes and loyalty have their own entitlement checks. Read the per-feature guide rather than assuming one permission unlocks all tabs.
• Opening-message tests can include C, but auto-promotion is two-arm only. Statistical conventions and repeated checks need review; a sample floor is not proof of certainty.
• Referral settings are inactive. Redemption tiers create manual-fulfillment tickets, while reward-catalog codes follow their configured delivery method.
• Content Studio produces drafts. External publication, sending and destination acceptance are separate steps, and performance outcomes are not guaranteed.

Troubleshoot this workflow

A rule affects unrelated products

Inspect matching scope, ordering, competing rules and source relevance. Revert or disable the narrow change and retest before increasing weight.

A reward deducted points but no usable discount appeared

Inspect delivery method, code-pool stock, redemption state and checkout. Manual-fulfillment tickets do not issue an instant coupon.

The designer preview works but the store does not

Check installation, correct store key, saved version, audience suppression, CSP and theme conflicts in a fresh actual storefront session.

Related next steps

• Rule matching and controls
• Supported experiment types
• Reward delivery and inactive referrals
• Designer setup and storefront testing

Page-by-page checklist

Configure a store safely

Outcome: Store configuration, integrations, billing, security, and access changes are scoped, tested, and auditable.

Why this sequence: Configuration can affect access, availability, billing or external systems. Distinguish a saved local setting from the provider's effective state, and know which part of the workflow a control actually governs.

When not to use it: Do not share an administrator account to bypass a capability check, raise a cap to mask a provider outage, retry an uncertain purchase or treat a legal download as a signed compliance agreement.

Prerequisites

• The capability required by the target route
• The exact store ID
• Provider or billing access where needed
• A safe test identity or credential

Procedure

1. Confirm the store ID and effective member capability before opening a sensitive settings route.
2. Make one scoped change in the owning screen: AI, budget, API key, billing, voice, replies, tool, legal, loyalty, notification, security, SLA, or team.
3. For connectors, complete provider authorization and test both inbound and outbound behavior; never rely only on a Connected badge.
4. For access or credentials, use least privilege, store secrets outside support messages, then test allowed and denied behavior.
5. For billing, confirm provider result, effective entitlement, next date, and invoice. For notifications, resolve the source issue before marking read.
6. Use Store Details and the owning settings screen to confirm the saved change. Billing history is in Settings → Billing; detailed audit records are restricted to Zubby platform administrators.

Completion evidence

• The change affected only the intended store
• Effective access or entitlement is verified
• Provider behavior is proven
• An audit or source record exists where implemented
• A recovery path is documented

Synthetic worked example

A fictional store owner wants a monthly AI model-spend cap while keeping the conversation allowance and subscription unchanged.

1. Confirm the intended store and your effective Settings capability. Open Settings, Data, AI Budget and record the current cap before changing it.
2. Read this month's tokens, estimated cost and request count. Inspect capability, provider and model breakdowns; estimated model cost is not a subscription invoice.
3. Choose an approved nonzero monthly cap, save with the owning control, then reload and confirm the stored amount and cap status. Do not use zero when intending to stop spend: zero removes the merchant cap.
4. Compare Billing separately for plan, conversation allowance and purchased packs. Changing a model-spend cap does not purchase capacity or change the subscription.
5. Record the prior value and responsible owner. Review usage after controlled work; in-flight calls and a platform ceiling mean the cap is not an exact invoice or a guarantee of uninterrupted AI availability.

Synthetic generic webhook envelope. The event ID, timestamp and data values below are illustrative; optional fields vary with the captured lead. Use a real controlled event and the current webhook contract to verify your receiver. Slack uses text and Zapier/Make flatten event data, so do not apply this envelope parser to every destination.

{
  "id": "00000000-0000-4000-8000-000000000001",
  "event": "lead.created",
  "timestamp": "2026-10-21T12:00:00.000Z",
  "data": {
    "leadId": "00000000-0000-4000-8000-000000000002",
    "email": "shopper@example.invalid",
    "name": "Test shopper",
    "purpose": "lead_capture",
    "shopperMessage": "Please send the approved product information.",
    "conversationId": null
  }
}

Expected result: The saved model-spend cap is visible after reload, the team can distinguish it from conversation capacity and invoices, and the prior value is available for an authorized reversal.

Limitations and consequential settings

• Billing, team and API keys have independent capability gates. Owners/admins have full access, while delegated team managers cannot grant capabilities beyond their permitted ceiling.
• AI Budget limits model spend separately from conversation allowance. Zero removes the merchant cap, but a platform ceiling can still apply; in-flight calls can finish and unavailable provider routing can block calls below the cap.
• Outbound event receivers belong under Integrations, Webhooks. Use that guide for raw-body signatures, deduplication, five-second timeouts and reconciliation; saving an AI budget does not configure event delivery.
• Freemius/Shopify/legacy billing routes, provider onboarding, legal parties and residency require their actual account or agreement evidence; source code alone cannot establish production configuration.

Troubleshoot this workflow

AI calls stop below the merchant cap

Check platform ceilings, provider routing and availability, effective entitlement and request errors before raising the cap.

The invoice differs from estimated model cost

Compare Billing provider charges, subscription, usage periods and approved packs. AI Budget estimates model spend, not total billing.

A saved setting has no expected effect

Check the owning Save control, effective capability, plan and external provider state. SLA changes apply to new tickets, and a billing confirmation must be reconciled with effective entitlement.

Related next steps

• Model spend and cap behavior
• Least-privilege API credentials
• Roles and capability overrides
• Provider-specific commercial terms

Page-by-page checklist