Troubleshooting SF Express pickup on Shopify

Common issues when setting up HK Pickup, plus a checkout verification checklist after install, theme embed, and admin settings.

Install HK Pickup on the Shopify App Store →

Verify checkout works

Use this on your live or preview storefront to confirm HK Pickup before go-live.

Before you test

App embed is on and the theme is saved
At least one pickup type is enabled in admin settings
The store sells to Hong Kong and shipping is configured for test orders

Open the delivery dialog

Add any product to the cart.
Open the cart — cart page or cart drawer.
Click Checkout.

Expected: A dialog titled Choose delivery (or your custom heading) with SF Express pickup and Ship to my address.

If nothing appears, see No dialog when clicking Checkout below.

Test SF Express pickup

Click SF Express pickup.
Use Service type, District, and Search to find a location.
Select a row (it should highlight), then Continue to checkout.

Expected: Shopify checkout opens with the pickup point prefilled in Shipping address. The customer still enters name, contact, and payment.

Order attributes (SF pickup) — Shopify Admin → Orders → Additional details:

Attribute	Expected value
`_sf_delivery_mode`	`pickup`
`_sf_pickup_code`	SF code for the location you selected (e.g. `H852K067P`)
`_sf_pickup_type`	`SF Station`, `SF Locker`, or `SF Partner Point`
`_sf_pickup_address`	Full pickup address
`_sf_pickup_region`	Region for the selected point
`_sf_pickup_district`	District for the selected point
`_sf_pickup_locale`	`zh-HK`, `zh-CN`, or `en-US` (matches storefront language)

These are written to the cart before checkout redirect, so they remain on the order even if the customer edits the prefilled shipping address.

Test home delivery

Return to the cart and click Checkout again.
Click Ship to my address.

Expected: The dialog closes and normal Shopify checkout opens — no SF pickup address prefilled.

Order attributes (home delivery) — Additional details should show _sf_delivery_mode = home and no _sf_pickup_* fields.

Cart page and cart drawer

Surface	How to test
Cart page	Go to `/cart`, click Checkout
Cart drawer	Add from a product page, open the drawer, click Checkout

Both should show the same delivery dialog. If one fails, see Dialog on cart page but not cart drawer.

Languages (optional)

Switch storefront language, then open checkout from the cart again. Dialog labels and filters should match the active language.

Quick checklist

Test	Pass
Dialog opens on checkout click	☐
SF pickup → location → prefilled checkout	☐
Home delivery → normal checkout	☐
Cart drawer checkout works	☐
Order attributes match tables above	☐

Developer mode: After wiring hkpickup.open(), run the same SF pickup and home delivery checks. Event testing — see Developer mode.

Developer mode

Symptom	Action
Developer mode on, dialog never opens	You must call `window.hkpickup.open()` or wire checkout buttons — see Developer mode
Developer mode off, no dialog on checkout	Enable app embed; see No dialog when clicking Checkout
Checkout goes straight to Shopify with dev mode on	Expected — add custom JS to open the dialog

No dialog when clicking Checkout

Check	Action
App embed off	Online Store → Themes → Customize → App embeds → HK Pickup → on → Save
Subscription / trial not active	Open Apps → HK Pickup — complete Shopify plan approval if redirected. Or Settings → Apps and confirm the app is installed and billed
Wrong theme	Enable embed on the published theme, not an old duplicate
Cached page	Hard refresh the storefront or test in a private window
Theme selectors	See Theme editor setup — try overrides if `auto` fails

Check the storefront response

If you forgot to approve the plan (or the trial ended), the storefront still returns HTTP 200 — not an error page.

Open your cart page.
Open browser DevTools → Network → reload the page.
Find the request to /apps/hkpickup/storefront-config.
Read the JSON body:
- "subscriptionActive": false → billing is not active. Checkout behaves like App embed off. Open Apps → HK Pickup and approve the plan.
- "subscriptionActive": true and still no dialog → embed or theme issue, not billing.

Dialog on cart page but not cart drawer

Save the theme after enabling the embed.
Add a product, open the drawer, click Checkout.
If still broken, set Cart drawer selector to cart-drawer in app embed settings.

Empty pickup list or “No pickup points found”

Check	Action
No pickup types enabled	Apps → HK Pickup → Pickup types — enable at least one
Filters too narrow	Clear Service type and District, clear search
New install	Wait a few minutes and retry

“Could not load pickup points”

Check your internet connection and retry.
Confirm the app is still installed (Settings → Apps).
If the error persists, email tech@k2.digital with your shop domain and a screenshot.

“Ship to my address” does not continue to checkout

In app embed settings, try Cart form selector → form#cart.
Test on the cart page first — if that works but the drawer fails, focus on drawer selector overrides.

Checkout says “Shipping not available”

This is usually a store configuration issue, not HK Pickup:

Hong Kong market and shipping profile
Product availability and inventory location
Order routing rules

HK Pickup prefills the shipping address for SF pickup — it does not create shipping rates. Fix shipping in Shopify Admin, then test again.

Wrong language in the dialog

Source	Fix
Storefront locale	Customer’s active storefront language
Customization off (default)	Built-in app extension locales; optional Translate & Adapt
Customization on	Apps → HK Pickup → Settings → Translations (en / zh-TW / zh-CN)

Go to Shopify Admin → Apps → HK Pickup to refresh your session. Saved settings are kept in HK Pickup — signing in again does not reset them.

Pilot mode

See Pilot mode for full setup. Common issues:

Symptom	Action
Pilot on, tester sees no dialog	Log in as a customer (not Admin only) → reload cart page → checkout
Pilot on, everyone sees dialog	Turn Pilot off for full launch; check allowlist is saved on published theme
Pilot on, nobody sees dialog	Add allowlist emails or set `window.HKPICKUP_PILOT_ALLOW` in theme.liquid
Email in list but no match	Check spelling (case-insensitive); customer account email must match exactly
Old app still shows for tester	Expected possible — public guests are unaffected; disable old embed briefly for tester-only window
Changed pilot in draft theme	Publish live theme — draft settings do not affect storefront

Verify Pilot mode behavior

When Pilot mode is on (migration from another app):

Who	Steps	Expected
Guest	Add to cart → Checkout	No HK Pickup dialog — normal / old-app checkout
Allowlisted tester	Log in as customer → reload cart → Checkout	Delivery dialog opens — run SF pickup and home delivery checks above
Tag-based tester	Empty allowlist + `HKPICKUP_PILOT_ALLOW` in `theme.liquid` + customer tag → reload cart → Checkout	Same as allowlisted tester — see Pilot mode → Theme flag
After go-live	Turn Pilot off → guest Checkout	Dialog for everyone; no tester emails in page config

Contact support

Email tech@k2.digital with:

Your .myshopify.com domain
Theme name (shown in app embed settings)
What you expected vs what happened
Screenshots or a short screen recording if possible