Troubleshooting

Most common issues and how to fix them. If your problem isn't here, check the FAQ or email dario@onlyfresh.com. Include your shop domain and the timestamp of the failing action — speeds up diagnosis.

Magic link email never arrives

Symptom: Agent (or buyer) requests a magic link, sees a "check your email" screen, but nothing shows up.

Common causes:

1. Spam / quarantine. Resend deliveries can land in junk on first contact. Have them check spam, then mark as "not spam".
2. Typo'd email. Look at the agent's profile — does it match what they entered? Common: name@gmial.com.
3. Resend hit a hard bounce previously. Once Resend marks an address as bounced, future sends to it fail silently. Check the Resend dashboard suppression list.
4. RESEND_API_KEY not set. Without the key, sendEmail returns {delivered: false, reason: "no api key"} — UI surfaces a warning toast. Self-hosters: set the key.
5. Rate limit hit. 5 requests per identity per 5 minutes. Wait and retry.

Fix: Re-trigger the magic link from the agent's profile (Send magic link). Watch the response toast for emailDelivered status.

Agent can't log in (says "no matching agent")

Symptom: Agent enters their email, OTP arrives, code is correct, but login fails.

Common causes:

1. Email mismatch. The OTP went to the email they typed, but no agent metaobject has that exact email. Case matters — Soryk normalises but check trailing whitespace too.
2. Agent is inactive. Their Active toggle is off. Re-activate from the agent profile.
3. Agent was deleted. Re-create them with the same email — past commission earnings are still attributed to that email tag.

Commission not calculated for an order

Symptom: Order is paid in Shopify but doesn't appear in Da pagare.

Diagnosis checklist:

• Is the order financial_status: paid? Soryk only counts paid orders. Pending or partially-refunded won't show.
• Does the order have a soryk_agent:<email> tag? If no tag, multi-agent fallback applies — check the company's agent assignments.
• Is the email in the tag a current Soryk agent? If they were deleted, the tag exists but no attribution happens.
• Is there a matching commission rule? Open Commissions → Regole — at least one rule must match (global is the safe baseline).
• If it's an online storefront order, is commissionsOnOnlineOrders on?

Commission amount looks wrong

Symptom: The number doesn't match what you expected.

Walk through:

1. Check which rule matched. Most-specific scope wins, ties broken by priority.
2. Check the rule's base. total includes tax + shipping; no_tax_no_shipping excludes both.
3. Check for an active soryk_commission_override on this order — overrides take priority over tags.
4. Manager override % stacks on top — verify whether the agent has a manager with a non-zero override.

Push notifications not firing

See the dedicated Notifications troubleshooting section. Quick checks:

• env vars set?
• Agent has Settings → Notifications toggled on?
• iOS user installed as app on iOS 16.4+?
• App build version current? Force-quit and relaunch the app.

CSV import fails

Symptom: Upload returns errors instead of created agents.

Common causes:

• Wrong column headers. Required: email, name. Optional: company_ids, locale, role. Headers are case-sensitive.
• Wrong GID format. Company IDs must be the full gid://shopify/Company/<numericId>. Just the number won't work.
• Smart quotes. If you pasted the CSV from Word, smart quotes (" vs ") break parsing. Re-export as plain UTF-8.
• Email regex fail. Spaces, missing @, double dots. Validate before upload.

Fix: The response body includes unresolvedCompanies and invalidRows — fix those rows in your CSV and re-upload. Imports are idempotent on email so re-running is safe.

Order tags look wrong (commas, spaces, weird chars)

Symptom: You expected tag soryk_agent:marco.bianchi@example.com but you see soryk_agent:marco_bianchi_example_com.

This is by design. Soryk runs every user-supplied tag value through sanitizeTagValue: lowercase, trim, replace whitespace/commas/quotes with _, strip non-[a-z0-9._@+-] with _. This prevents tag injection (e.g. an email with a comma would otherwise create two tags).

The commission engine indexes the email→agent map both raw and sanitized, so attribution still works correctly. You can safely ignore the cosmetic difference in the tag — it's intentional.

Buyer portal shows blank screen

Symptom: Buyer signs in successfully but the catalog/orders pages are empty.

Common causes:

• No companyId in session. The buyer's email exists in Shopify but isn't linked to any Company. Add them as a contact on a B2B Company.
• Company has no B2B catalog assigned. Open the company in Shopify admin and verify a catalog is attached.
• Browser cookie blocked. Some corporate firewalls strip cross-site cookies. Buyer should try in a regular browser session.

Draft order creation fails

Symptom: Slide-to-confirm shows error toast.

Common error codes (UI-localized):

• COMPANY_HAS_NO_CONTACT — the company / location has no primary contact email. Add one.
• INVALID_INPUT — usually a quantity issue (zero or negative on a line). Re-check the cart.
• NOT_AUTHENTICATED — session expired. Re-login.
• SHOP_NOT_CONNECTED — Shopify access token revoked (admin uninstalled and reinstalled). Re-auth from admin.

Analytics looks stale

Symptom: A new paid order doesn't appear in the dashboard for a few minutes.

Live periods (this week / month / year) cache for 60 seconds. Custom past ranges cache for 5 minutes. Refund webhooks invalidate the shop's cache automatically. If you need a hard refresh: change the period to Custom range with a different end date and back — that builds a fresh cache key.

Audit log shows orphan warning

Symptom: The Audit log page shows "N orphan entries detected".

This means the Upstash Redis mirror has entries that no longer have a matching soryk_audit_log metaobject in Shopify. Possible causes:

• Someone deleted audit log metaobjects directly via the Admin GraphQL API. Investigate who has access.
• Shopify metaobject was deleted as part of a bulk cleanup script. Stop the script.
• Rare: Shopify-side data drift. Contact support if you see this without a known cause.

The orphan count is a security signal — investigate before dismissing.

Geo territory shape doesn't match real locations

Symptom: An agent's circle covers Milan, but Milan companies don't appear in their list.

Cause: Shopify CompanyLocation doesn't expose lat/lng natively. Geo shapes (circles + polygons) silently skip on real CompanyLocations until coordinates are provided. See the CompanyLocation caveat.

Workarounds:

• Use country / region / ZIP rules instead — they work out of the box.
• Add a per-location geocoding step (Nominatim or Mapbox) writing lat/lng to a custom metafield. Ask support for the example script.

Discount stuck on "pending approval"

Symptom: Agent applied a discount, but the order shows soryk_discount_pending tag and isn't placeable.

Cause: The discount % is above agentDiscountMaxPercent. The order is queued in Admin → Discounts for merchant approval.

Fix: Either approve from the queue, or raise the cap in Settings → Ordering if this happens often for legitimate reasons.