Help & Documentation

Key terms

Recent updates

Include changes that affect merchant setup or storefront behavior. Omit internal doc edits and minor fixes unless behavior changes.

• 2026-07-13 — Help documentation published.
• 2026-07-08 — Privacy Policy effective; GDPR tools under Settings → Customer data (GDPR).

1. Why Scale & Tail

Generic upsell apps treat every shopper the same. For multi-species pet stores, that means wrong species, wrong category, and missed habitat add-ons when buyers are ready to spend.

• Species-first — shoppers pick their pet; recommendations respect it
• Two mapping modes — Collection mappings for scale, Manual associations for precision
• Complement rules + Custom groups — cross-category logic, not duplicate SKUs
• Smart Cart drawer — species picker, cart, and What your pet also needs
• Recommendation metrics — impressions, clicks, add-to-carts, purchases

Before / after

Scenario: Shopper adds UVB lighting for a bearded dragon. Generic apps push more lighting. Scale & Tail suggests setup-completing categories via complement rules.

See it in your store: complete Step 3, open Smart Cart, and read Storefront experience.

2. Quick start checklist

The in-app Get started page mirrors this list. Finish setup needs Required for launch only; then home becomes Dashboard.

3. Step 1 — Add species

Sidebar: Species · Get started → Add species

1. Click Add species.
2. Enter Species name and Sort order (lower = first).
3. Click Save.

Manage with Edit, Deactivate / Activate, Delete. Storefront icons are emoji matched from the name.

Checklist: ☐ ≥1 species shows Active

4. Step 2 — Link products to species

2A Collection mappings (bulk)

Create: Add collection mapping → Search → Create mapping → species → Create

Sync: Sync (row) fills missing links · Sync all (header) syncs every mapping

Checklist: ☐ ≥1 mapping · ☐ Sync done · ☐ product–species links > 0 on Dashboard

2B Manual associations (precision)

Sidebar: Manual associations (main sidebar—not Recommendation tuning)

Single: Search products → Search → Edit → species → Save

Batch: select rows → Batch set species (N) → Update (N)

Sources: Collection badge = sync; no badge = manual.

5. Step 3 — Enable the storefront widget

Get started or Settings → Storefront widget

1. Open theme editor (App embeds)
2. App embeds → enable Scale & Tail → Save
3. Hard-refresh storefront

Checklist: ☐ Smart Cart visible on live store

6. Step 4 — Tune recommendations

4A Custom groups

Recommendation tuning → Custom groups

Add group · Deactivate / Activate · Restore defaults (app groups + rules only; Shopify metafields unchanged)

Shopify: Products → metafield Custom group (scale_tail.custom_group)

Progress: Dashboard → Custom groups: X% tagged · Metrics → Refresh catalog count

4B Complement rules

Recommendation tuning → Complement rules · Filter by scope

Substrate: bedding in the cart often pairs with maintenance tools and enclosure cleaning—not more bedding.

Edit: Edit / Add / edit rule → Scope, When cart contains group, Recommend products from → Save

Copy defaults: species buttons under Copy shop default rules to a species…

7. Storefront experience

Recommendations live inside the cart drawer on any page with the widget enabled—not in the homepage body.

Smart Cart & cart drawer

┌──────────────────────────────────────────────┐
│  Storefront (any page)         ┌ Smart Cart┐
└────────────────────────────────┴───────────┘
              ↓ opens drawer
┌ Cart ──────────────────────────────── [×] ─┐
│ Pet: … [Change]                           │
│ ── line items ──  Subtotal · [Checkout]     │
│ What your pet also needs                    │
│ [ recommendation cards ]                    │
└───────────────────────────────────────────┘

Auto-selection: If you have exactly one active species and the shopper has not chosen a pet before in this browser, that species is pre-selected. Multiple active species → picker until the shopper chooses.

What your pet also needs

Collapsible section; Add to cart in drawer. Requires species, Enable cart recommendations, active trial/plan, and Admin product links.

Theme cart vs Smart Cart

Theme cart icon → Shopify cart. Smart Cart → Scale & Tail drawer (unless theme calls ScaleTail.openCart()).

8. Recommendation metrics

Metrics · Recommendation metrics · Refresh catalog count · Reload

Funnel: CTR, Add-to-cart rate, CVR. Coverage: In-pool reach rate, Catalog penetration. Rates hidden until 100 impressions.

9. Settings reference

Settings → Save settings

GDPR export: Returns Scale & Tail–stored data for the requested customer (species selections, recommendation/behavioral events, purchase attribution). Does not replace full order history in Shopify Admin.

10. Billing, trial & uninstall

No active trial/subscription → Subscription required → Choose a plan.

Uninstall

1. Shopify Admin → Apps → uninstall Scale & Tail.
2. Smart Cart stops loading immediately.
3. Shopify sends shop/redact after the mandatory waiting period; we delete app data (Privacy Policy).
4. Reinstalling after deletion starts a fresh setup—data is not automatically restored.

11. Troubleshooting & FAQ

Decision guide

Getting started & storefront

I don’t see recommendations on my homepage — Expected. Open Smart Cart; recs are in the drawer.

Theme cart vs Smart Cart — Theme cart ≠ Scale & Tail. Use Smart Cart.

Smart Cart button missing — App embed on, theme Saved, hard-refresh. → Step 3

Recommendations

No recommendations in drawer — Species selected? Products linked? Enable cart recommendations? Active plan/trial? → Decision guide

Wrong or repetitive suggestions — Sync all, Custom group tags, Complement rules, Manual associations.

Placeholder cart image — Add featured image in Shopify Products.

Configuration

Where is Manual associations? — Main sidebar, not Recommendation tuning.

Force sync vs Sync — Sync = missing links only. Force sync = overwrite. → 2A warning

503 / species fetch failed — Refresh; contact support with shop domain if persistent.

Data & billing

Metrics dashes — Need ≥100 impressions.

GDPR export — Settings → Customer data (GDPR). Scope in §9.

12. Privacy & customer data

Privacy Policy — how Scale & Tail collects, uses, stores, and deletes merchant and customer data. Required for App Store listing; separate from this setup guide.

GDPR exports: Settings → Customer data (GDPR). Uninstall: see §10 and Privacy Policy.

13. Contact support

Email: support@scaletail.pet

Include: shop domain, summary, screenshots, steps tried.

We aim to reply within 1–2 business days. Billing and access-blocking issues are prioritized.