Pilot mode — test SF Express pickup on a live Shopify store

Use Pilot mode when you are migrating from another SF Express pickup app and need to test HK Pickup on a live store without changing checkout for all customers.

Install HK Pickup on the Shopify App Store →

While Pilot mode is on, only allowed testers see the HK Pickup delivery dialog at checkout. Everyone else keeps your current checkout flow (native checkout or your old app).

Turn Pilot mode off when you are ready for full launch, then disable the old app.

When to use Pilot mode

Situation	Use
Replacing another pickup app on a live store	Pilot mode
Normal live store (no old app)	Pilot off
Custom JavaScript / multiple checkout apps with your own triggers	Developer mode — not Pilot mode

Pilot mode applies to normal live checkout intercept only. When Developer mode is on, Pilot settings are ignored.

Setup (theme editor)

Online Store → Themes → Customize
App embeds → HK Pickup — ensure the embed is on (Theme editor setup)
Turn on Pilot mode
Add Allowed test emails (one per line), or leave empty and use a theme flag (below)
Save the live theme (unpublished draft changes do not affect your storefront)

Allowed test emails

One email per line (case-insensitive)
Tester must log in as a customer on the storefront (Shopify Admin login does not count)
After login, reload the cart page, then click Checkout
Use test/staff customer accounts only — while Pilot mode is on, allowlist and logged-in customer email appear in page HTML (DevTools). When Pilot mode is off (production), those values are not included in window.hkpickupConfig.

Theme flag (optional)

If the allowlist is empty, set window.HKPICKUP_PILOT_ALLOW in theme.liquid before the app embed loads:

<script>
  window.HKPICKUP_PILOT_ALLOW = {% if customer.tags contains 'hkpickup-pilot' %}true{% else %}false{% endif %};
</script>

Tag customers in Shopify Admin (Customers) with hkpickup-pilot, or use your own Liquid logic.

When the allowlist has any emails, the list takes precedence — the theme flag is ignored.

Migration workflow

1. Keep old app running for public customers
2. Enable HK Pickup app embed + Pilot mode + allowlist
3. Log in as tester customer → reload cart → test SF pickup + home delivery
4. Turn Pilot mode OFF → all customers get HK Pickup
5. Disable the old app embed

See Verify checkout and the Testing checklist below.

FAQ — common “bugs” that are expected

Symptom	Likely cause	Fix
“Pilot doesn’t work after I logged in”	Cart page loaded before login	Reload cart after customer login
“I’m the store owner but no dialog”	Admin session ≠ customer login	Log in on storefront as a customer with allowlisted email
“Pilot ON but nothing changed on live site”	Settings saved on draft theme only	Publish live theme
“Only some customers see pickup”	Pilot still on	Turn Pilot mode off for full launch
“Email is correct but no dialog”	Typo in allowlist or wrong customer account	Check allowlist spelling; emails are case-insensitive
“Nobody sees pickup with Pilot ON”	Empty allowlist and no `HKPICKUP_PILOT_ALLOW`	Add emails or theme flag
“Old app still appears for testers”	Both apps intercept checkout	Public guests are unaffected; testers may need to briefly disable old app embed — see Troubleshooting → Pilot mode

Testing checklist

Pilot off → guest checkout → dialog opens (regression)
Pilot on + your email in list → guest → no dialog
Log in as that customer → reload cart → checkout → dialog opens
Complete SF pickup and home delivery paths on your storefront
Pilot off → guest → dialog for everyone again
(Optional, pending) Empty allowlist + HKPICKUP_PILOT_ALLOW + customer tag — see Theme flag above (P6 signed off 2026-08-09)

Theme editor setup — app embed master switch
Developer mode — custom hkpickup.open() integration
Troubleshooting