1. Permission screens & amber banners
Most "X doesn't work" reports are one missing Shopify permission. Sublyra asks for everything on the single consent screen at install — stores that installed before a permission was added see an amber "Additional permission needed" banner with a Grant access button the first time they open the page that needs it.
| Symptom | Likely cause → fix |
|---|---|
| Amber "Additional permission needed" banner on a settings page | The store installed before this permission existed → click Grant access, approve on Shopify's screen (one click), then retry whatever you were saving. |
| Shopify shows an approval screen after an app update | Normal — Sublyra requests all scopes on one screen. Click Approve / Update once; every feature works from then on. |
| Customer status tags not applied | Missing write_customers → grant via the banner on Settings → Tags & shipping, then save the tag rules again. |
| Subscription shipping profile won't create | Missing read_shipping/write_shipping → grant via the banner on Settings → Tags & shipping, then click Create shipping profile again. |
| Renewal inventory check not working | Missing read_inventory → grant via the banner on Settings → Inventory policy. |
There is no "approve it for me" service. Shopify requires the store owner's own click on its approval screen — no app can approve permissions by itself.
2. Discount & sync errors
| Symptom | Likely cause → fix |
|---|---|
| Bundle, quantity-break, upsell, loyalty or membership save fails with a discount error | Missing write_discounts on an older install → click Grant access on the amber banner at the top of that page, approve, then save again. New installs never see this. |
| Bundle shows wrong prices on the storefront | Product prices are snapshotted into the storefront metafield at save time → re-save the bundle after changing prices in Shopify. |
| Quantity break missing products from a collection | Collection scopes are expanded to products at save time (up to 250 per break) → re-save after changing collection membership. |
| Upsell rule rejected on save | A rule with no offer products is rejected → tick at least one product before creating it. |
| Member discount not applying | The automatic product discount only applies to customers tagged sublyra-member → check the customer carries the tag. (Automatic tagging on signup is on the roadmap.) |
| Klaviyo card shows a red "Last sync failed" banner | The private API key is wrong or was deleted in Klaviyo → create a new pk_… key, paste it into the card, click Send test event, then save. |
| Mailchimp test says the key has no data-center suffix | You copied only part of the key → copy the whole key including the dash and ending like -us6. |
3. Widget not showing
| Symptom | Likely cause → fix |
|---|---|
| No subscribe-and-save block on the product page | Work the Setup checklist in order: (1) a selling plan group exists and the product is attached — nothing is subscribable until a group exists; (2) the Subscribe & Save block is placed on the theme — Online Store → Themes → Customize, add the block above Add to cart (or use the one-click placement on the Setup page); (3) open the product on the storefront to confirm. |
| Widget shows on some products but not others | Only products attached to a selling plan group are subscribable → open Selling plans, search for the product and tick it. |
| One-click placement didn't reach the product page | Vintage themes without JSON templates can't be placed automatically → use Open in theme editor on the Setup page and add the block by hand. |
| Widget appears but the store is password-protected in testing | Turn off the storefront password (Online Store → Preferences) before testing as a shopper. |
| Widget styling looks off on my theme | Try a style preset on the Widget settings page first; for anything beyond that, use the scoped custom CSS under Settings → Developer — it's scoped to the widget so it can't leak into the theme. |
4. Emails & texts not sending
| Symptom | Likely cause → fix |
|---|---|
| Win-back emails not going to a cancelled subscriber | Win-back only emails customers with marketing consent — check the consent badge on the Customers page. Also confirm win-back is turned on (Retention → Win-back) and the wait period has passed. |
| Card-update (dunning) emails not arriving | These are transactional and always send — check the subscriber's spam folder first, then that the retry schedule for that decline reason isn't empty (Settings → Payment recovery). An expired card is never retried into success; the customer must update it first. |
| SMS not sending at all | One of the three Twilio fields empty (SID / token / from-number), or the master switch off → Settings → SMS notifications, re-save all three together and tick Enable SMS notifications. Send a test SMS to confirm. |
| SMS sends to some customers but not others | Texts only reach customers with a phone number on their Shopify record → everyone else simply gets email. That's by design: incomplete records degrade quietly, not loudly. |
| Test SMS fails | Typo in the from-number (use +country-code format, no spaces), a Twilio trial account texting an unverified number, or no Twilio credit → fix in your Twilio console; see the Twilio setup walkthrough. |
5. Scheduled jobs (retries, win-back)
| Symptom | Likely cause → fix |
|---|---|
| Failed charges never retry | Check the retry schedule on Settings → Payment recovery: wait intervals are days separated by commas, and an empty field means "never auto-retry that reason". If schedules look right but nothing moves, the scheduled-jobs ticker may be paused — contact support with your store URL; job scheduling is operated by Sublyra, and we can see it from our side. |
| Win-back emails stopped entirely | Same scheduled-jobs check — if retries also stopped, it's the ticker, not your settings. If only win-back stopped, re-check the win-back toggle and wait days on Retention → Win-back. |
| Retry happened but the customer was never emailed | Retry attempts and reminder emails are separate toggles — check both the retry schedule and the email settings on the Payment recovery page. |
How to tell it's working: Settings → Logs shows job activity — billing attempts, tag changes, portal actions — newest first. If the log is quiet when it shouldn't be, that's the signal to reach out.
6. Everything else
| Symptom | Likely cause → fix |
|---|---|
| Migration preview says "No data rows found" | The CSV's first line must be the header, with at least an email and a variant id column → check you pasted the whole file and picked the right source app. See Migration. |
| Analytics is empty but you have subscribers | You may be viewing sample-data-free pages before the first webhooks land — check Settings → Logs for recent events. If it's truly empty after real orders, contact support. |
| "Sample data is on" banner won't go away | Click Remove sample data on the banner itself — clearing is one click and only affects the fictional dataset. See Analytics. |
| Plan change didn't take effect | The Shopify approval screen was declined or closed — the page shows "The charge was not completed — nothing changed" → start the switch again and approve on Shopify's screen. See Plans & billing. |
| API requests return 401 | The key was revoked (revoking is instant) or typo'd → generate a fresh key on Settings → Integrations. Keys badged Legacy should be rotated regardless. |
Still stuck? Open the in-app Help page and use the chat bubble, or email via sublyra.com/support — replies land within one business day. Include your store URL and a screenshot of the symptom so we can look at your setup directly.