Pickup points in headless storefronts and mobile apps

Globe’s cart widget lives in a Shopify theme. A native mobile app built on the Storefront API, or a headless web storefront such as Hydrogen or Next.js, has no theme to put it in. This guide shows how buyers of those apps choose a pickup point before they reach Shopify checkout.

Both options below save the point on the Storefront API cart as cart attributes. From there, checkout and order processing treat the point exactly like one chosen in the cart widget.

---

Choose an option

	A: Hosted selection page	B: Storefront pickup API
What you build	Open a URL in a WebView, popup or iframe	Your own map or list, in your app’s UI
UI	Globe’s map, list, search, geolocation and carrier filter	Yours
Who writes the cart	Globe	Your app, with cartAttributesUpdate
Credential	None. The page runs on your store’s domain	A publishable key (glb_pk_…)
What your app handles	Opening the page and reading the result	Location, search, the point list and the cart write

Start with A if you want it working fast. Choose B when the picker has to look and feel native. You can switch later: both write the same cart attributes.

---

Before you start

• Globe is installed with an active plan.
• Headless pickup is turned on for your store. We enable it per store: ask us in the in-app support chat. Until then, Settings → Headless and mobile apps only shows Request access, and the selection page and the Storefront pickup API answer that the feature is not enabled.
• At least one pickup point carrier is set up and mapped to shipping methods. See Adding pickup point carriers.
• Your app creates carts with the Storefront API and sends buyers to the cart’s checkoutUrl.

---

Set up Globe

In the Globe admin, go to Settings → Headless and mobile apps.

For the hosted selection page

1. Under Pickup point selection page, click Turn on.
2. Under Return URLs, click Add return URL and add every address the page may send buyers back to:
   • an app deep link, for example myapp://pickup,
   • a universal link or Android App Link, for example https://app.example.com/pickup,
   • a web address of your headless storefront, for example https://shop.example.com/cart.
3. Click Save in the save bar.

Return URLs are optional if your app reads the result through a native bridge or postMessage only. They are required for redirects, and web origins for postMessage come from the https return URLs. See Return URLs.

If the card says Globe needs the storefront cart permissions, open Globe from your Shopify admin once and approve the updated permissions. Until then the page shows that selection is unavailable.

For the Storefront pickup API

1. Under Storefront pickup API, click Create key and copy the publishable key.
2. Optional: under Allowed web origins, click Add origin and add the origins of your web storefront, for example https://shop.example.com. With no origins listed, any website can use the key. Native apps are never affected.
3. Click Save in the save bar.

A publishable key only searches your carriers’ pickup points, so it is safe to ship inside an app or a browser bundle. See Authentication.

---

Option A: hosted selection page

1. Create or load the buyer’s cart with the Storefront API and keep its id.

2. Open this URL on your store’s domain:

   https://{shop domain}/apps/appfleece-globe/select?cart={URL-encoded cart id}&return_url={allowlisted URL}&state={your value}

3. The buyer picks a point. Globe verifies it with the carrier and writes the cart attributes.

4. Your app gets the result: a redirect to return_url, a native bridge message, or postMessage.

5. Query the cart again and continue to checkoutUrl.

Full parameters, result messages and code for iOS, Android, React Native and Hydrogen are in Hosted selection page.

Option B: Storefront pickup API

1. Ask for the buyer’s location, or let them move a map.
2. Search: GET https://api-globe.appfleece.app/v1/storefront/pickup-points?country=CZ&latitude=…&longitude=… with the header X-Globe-Publishable-Key.
3. Show the points. When the buyer picks one, take its cart_attributes.
4. Merge them into the cart’s existing attributes and write the list with the Storefront API mutation cartAttributesUpdate.
5. Continue to checkoutUrl.

Endpoints and code for curl, Swift, Kotlin, TypeScript and Hydrogen are in Storefront pickup API.

---

The cart attribute contract

Both options end with these attributes on the cart:

Key	Value
globe_PickupPointId	The point’s ID
globe_PickupPointName	The point’s name
globe_PickupPointAddress	The address on one line
globe_PickupPointData	The full point as a JSON string
globe_DeliveryMethod	pickup
globe_PickupPointCustomerId	The DHL Postnummer, else empty

Write the full cart_attributes exactly as the Storefront pickup API returns them. Globe accepts globe_PickupPointId alone only as a fallback, and only for carrier networks Globe stores itself: for carriers Globe queries live, such as GLS or DHL, an ID alone cannot be verified and the point is not saved on the order.

When the buyer switches to home delivery, remove the point keys from the cart. Cart attributes has the full contract, the ID-only fallback and what home delivery should write.

---

What happens at checkout

Checkout reads the cart attributes through Globe’s delivery customization, if you turned it on in Settings → Cart Widget → Checkout delivery customization:

• Only the shipping rates of the selected point’s carrier stay visible.
• If you set up rate renaming there, the rate shows the point’s name.
• If the buyer changes the delivery country in checkout to one the point is not in, checkout shows all rates as usual.

With the hosted selection page and Checkout address prefill on, checkout also opens with the point’s address as the delivery address. The buyer can still change it. The Storefront pickup API leaves the delivery address alone.

What happens when the order is created

When Shopify creates the order, Globe reads the cart attributes and verifies the point with the carrier’s network. This applies to every channel, the theme cart widget included.

Result	What Globe does
The point exists and is active	Replaces the point’s name, address and coordinates with the carrier’s data, saves it on the order (metafield Globe.PickupPoint) and applies the carrier’s tags, order attributes and note
The point is not found, inactive, of another country, of a carrier not mapped to the order’s shipping method, or the shipping method is not a pickup rate	Saves no point. The order gets the Unselected Pickup Point Orders tag (default point_unselected) if you set one, and the usual reminder flow applies
The carrier cannot be reached	Keeps the point from the cart’s globe_PickupPointData as it is
The cart had only globe_PickupPointId and Globe could not verify it (always the case for carriers Globe queries live, such as GLS or DHL)	Saves no point and applies the unselected tag

Labels, exports and ERP or WMS integrations see the same fields as for orders from your online store. See Point metafield.

---

Troubleshooting

The page says “Pickup point selection is not enabled for this shop.” Turn on the page in Settings → Headless and mobile apps. If that section only shows Request access, headless pickup is not enabled for your store yet. Ask us in the support chat.

The Storefront pickup API answers 403 access_required with “Headless pickup is not enabled for this shop.” The feature is enabled per store. Ask us in the support chat. A key created earlier starts working once it is on.

The page says “This cart no longer exists.” The cart expired, was already converted to an order, or belongs to another store. Create a new cart and open the page again.

The page says “This return address is not allowed for this shop.” return_url does not start with one of your return URLs. Check scheme, host and path. Subdomains are not matched.

The page says “Pickup point selection is temporarily unavailable.” Globe has no active plan, or the storefront cart permissions were not approved. Open Globe from your Shopify admin.

The page asks for a password. The online store is password protected, as development stores are. Enter the storefront password once in the same WebView or browser.

The order has no pickup point. Check the order’s tags for your unselected tag. Then check that the cart had globe_PickupPointData before checkout, that the buyer chose a pickup rate of the same carrier, and that the delivery country matches the point’s.

The API answers 403 origin_not_allowed. Add the website’s origin under Allowed web origins, or remove all origins to allow any website.

The API answers 429 rate_limited for every buyer. Your server is calling the API for all buyers from one IP address. Call it from the buyer’s device or browser instead. See Rate limits.

Checkout shows pickup rates of other carriers. Turn on Checkout delivery customization in Settings → Cart Widget, and make sure the cart has globe_PickupPointData, not only the ID.