In-Store Pickup
The In-Store Pickup module brings Magento's in-store pickup (part of Magento Inventory) to Hyvä Checkout. Customers choose between Ship to me and Pick up in store at the top of the shipping details, then pick a store that can supply their cart. The Hyvä team maintains this module.
Beta release, not for production use
The In-Store Pickup module is in beta. It is intended for testing and evaluation only. Do not run it on a production store. Install it in a development or staging environment so you can validate it ahead of a stable release.
Requirements for In-Store Pickup
The In-Store Pickup module works on both Hyvä Checkout lines:
- Hyvä Checkout 1.x: version
1.3.15or later. - Hyvä Checkout 3.x: version
3.0.0or later, with the Magewire 1 backward compatibility module (v1bc) enabled. The module's components are written for Magewire 1, and the refreshes that follow the delivery choice and the store choice go through v1bc. - Magento: the Magento Inventory in-store pickup modules enabled, and the In-Store Pickup Delivery shipping method enabled for the website.
The module's source is in the In-Store Pickup repository.
Installing the In-Store Pickup Module
Composer only installs a beta when the version constraint or your project's stability settings allow it, so require the module with the @beta flag:
Installation
After installing, rebuild your Hyvä theme's Tailwind CSS. The module styles the delivery choice and the "Collection Details" heading with Tailwind utilities, and those only work once they are compiled into the theme's CSS.
Magento Settings That Make In-Store Pickup Available
Hyvä Checkout offers in-store pickup only when Magento itself does. The Magento Inventory In-Store Pickup modules ship with every Magento 2.4 install, so nothing extra is needed there, but several settings must all be correct. Each of them fails silently: no error, no log entry, just no Pick up in store choice at checkout. Work through the settings below in order.
Enable the In-Store Delivery Carrier
Set Stores → Configuration → Sales → Delivery Methods → In-Store Delivery to Yes. In-Store Delivery is the carrier behind the pickup shipping method. The same section holds the search radius the store dialog uses when customers look up a store.
Flag the Source as a Pickup Location
Open Stores → Inventory → Sources (the top-level Stores menu, not Stores → Configuration) and edit the source that represents your store:
- Use as Pickup Location: Yes
- a full street address
- latitude and longitude filled in
The coordinates are not optional. Magento leaves out any pickup location without them, even when everything else is correct.
Take the Website off Default Stock
A website running on Magento's built-in Default Stock never shows pickup locations, because Magento excludes Default Stock from in-store pickup entirely. Most single-store installs run on Default Stock, so this is the step that catches most first setups.
Create a custom stock under Stores → Inventory → Stocks → Add New Stock and fill three fields:
- Name: anything recognizable
- Sales Channels → Websites: tick your website. All unassigned sales channels are assigned to Default Stock, so ticking the website here is what moves it off.
- Sources → Assign Sources: add the pickup location source
Save the stock, then reindex:
Afterwards the Manage Stock grid shows your website against the new stock, and Default Stock with none.
Choose a Distance Provider for the Store Search
The store search finds and sorts pickup locations by distance, so Magento needs a way to turn a town or postcode into coordinates. Pick a provider under Stores → Configuration → Catalog → Inventory → Distance Provider for Distance Based SSA:
-
Offline calculation needs no API key, but it reads a local geonames table that starts empty. Import it once for each country the store serves:
Repeat the command for each country code, or pass several separated by spaces:
nl be de. Without the import, a search by town or postcode resolves to nothing and the store dialog lists no stores. -
Google works without the import but requires a Google API key.
Assign Every Product to the Pickup Location Source
Magento offers a pickup location only when every product in the cart has a source item at that location's source. The quantity doesn't matter, and zero is fine: the source item just has to exist.
This is the usual cause of in-store pickup that "works sometimes". One product that is not assigned to the store's source hides the store for the entire cart, with no explanation. When Pick up in store appears for one cart and not for another, check the source assignment of every product in the cart that fails. See also Stock Checks at the Chosen Pickup Store.
How Customers Choose Delivery or Collection
The Ship to me / Pick up in store choice appears at the top of the shipping details section, directly below the contact details. Hyvä Checkout shows the choice only when the cart can actually be collected, using Magento's own check.
| Choice | What the checkout shows |
|---|---|
| Ship to me (the default) | The usual checkout, except that in-store pickup is left out of the shipping methods. |
| Pick up in store | The shipping address section becomes "Collection Details", in-store pickup is selected, and no other shipping method is offered. The customer chooses a store from the pickup method, and the billing section stops offering "My billing and shipping address are the same". |
The delivery choice keeps no state of its own. It follows the quote's shipping method, which is what choosing sets. A reload, a resumed session, or a shipping method selected anywhere else always agrees with the control.
Switching back to Ship to me gives up the pickup location and leaves no shipping method selected, so the customer chooses from the delivery options as usual.
Choosing a Pickup Store in Hyvä Checkout
Customers choose a store in a dialog that belongs to the in-store pickup shipping method. The dialog searches around a town or postcode with Magento Inventory's own area search, within the radius set in Stores → Configuration → Sales → Delivery Methods → In-Store Delivery → Search Radius (carriers/instore/search_radius). The dialog lists only the stores that can supply the cart, 20 per search by default.
The dialog opens on the town from the quote's address. When the quote has no address yet, it lists every store.
The store search cleans up the search term before it runs:
- SQL wildcards (
%,_) and the Magento Inventory delimiter (:) are removed from the term. - A term shorter than two characters is not searched, and a term longer than 128 characters is cut short. Both lengths are configurable (see Customizing In-Store Pickup).
- The Magento Inventory offline geocoder only knows coarse postcodes, so a full postcode such as
B5 4BUis searched asB5.
The minimum length exists because the geocoder matches towns by prefix with no row limit. A one-letter search would measure the distance to most towns in the country, and a two-letter prefix can still match many towns.
Stock Checks at the Chosen Pickup Store
The In-Store Pickup module checks whether the chosen store can supply the cart twice: when the customer chooses the store, and again when the order is placed. The place order check runs as a rule in Magento's QuoteValidationComposite, next to the Magento Inventory rules, so orders placed through the REST API are covered too. Magento Inventory's own place order rule only checks that the pickup location exists, and the cart can change between choosing a store and placing the order.
Stores are always looked up in the quote's website, not the current one.
If the cart changes so that no single store can supply it, the checkout drops in-store pickup the next time it opens and tells the customer that their order will be shipped.
What \"can supply\" means
A store can supply the cart when every product in the cart is assigned to the store's source. This is the Magento Inventory definition, and the quantity held at the source is not checked. A store whose stock of a product has run down to zero is still offered, exactly as in the Luma checkout.
Shipping and Billing Addresses for Pickup Orders
The Store's Address Becomes the Shipping Address
Choosing a store makes the quote's shipping address the store's address, through Magento Inventory. Magento Inventory keeps the customer's details on that address, so the In-Store Pickup module clears every field the store has no value for: the name, phone and company, and any other customer address attribute, including attributes a merchant adds and Adobe Commerce customer attributes. Switching back to Ship to me clears the store's details again.
The store's fields are the ones Magento Inventory fills from the pickup location (the inventory_convert_pickup_location fieldset), plus the name and phone taken from the store. Every other customer_address attribute counts as a customer field. To keep another field on the store's address, see Keeping More Fields on the Store's Address.
Billing Address Is Always Asked For
While the order is being collected, the In-Store Pickup module withholds "My billing and shipping address are the same" and always shows the billing form. When the checkout collects the billing address first, the checkbox sits on the shipping side instead, and the module withholds it there too.
The checkbox has nothing to offer on a pickup order. The shipping address is the store's, built entirely from the pickup location, so reusing it would put the shop's own address on the customer's invoice, and from there on the order, its emails and the admin. Hyvä Checkout implements the checkbox by copying one address onto the other, so this is exactly what the checkbox would do. With the billing address collected first, it would copy the customer's billing address over the store's address instead.
Magento Inventory does not prevent this on its own. Its DoNotUseBillingAddressForShipping plugin only guards the $useForShipping argument of BillingAddressManagementInterface::assign(), and Hyvä Checkout writes to the quote directly. What Magento Inventory does do is switch same_as_billing off while converting the address to the store's, so a cart cannot arrive in this state, only be put into it. The In-Store Pickup module drops the flag as soon as the customer chooses to collect, before a store is picked, and withholds the control.
The module does this through a plugin on AddressView::ownsSameAddressToggle(), which Hyvä Checkout asks before it renders the checkbox on whichever address is collected second. Both address sections remain the standard Hyvä Checkout templates, and the checkbox remains the standard SameAddressToggle component. Nothing about them is overridden.
Pickup Orders on the Order Success Page
After a pickup order is placed, the order success page shows a "Collect your order in store" card with the chosen store's details. The module adds the card to the order.success.additional.info container.
In-Store Pickup and Method Auto-Select
In-store pickup has no valid state without a chosen store, so the In-Store Pickup module never lets it be selected automatically. When the experimental auto-select first available shipping method setting picks in-store pickup, the module clears that selection.
The module cannot tell an automatic selection from a customer's. With that experimental setting on, a customer who chose to collect but has not chosen a store yet is moved back to delivery whenever Hyvä Checkout initializes the checkout again.
Customizing In-Store Pickup
The In-Store Pickup module is configured through Magento settings, di.xml arguments and layout XML. The table lists the options, and the sections after it show the ones that need code.
| To change | Do this |
|---|---|
| How far from the searched town stores are listed | Set carriers/instore/search_radius, the Magento Inventory setting. |
| The shortest and longest search term | Set minSearchTermLength and maxSearchTermLength in a di.xml (see Changing the Store Search Term Length). |
| How many stores a search lists | Set the pageSize argument of Hyva\CheckoutInStorePickup\Model\PickupLocationSearch in a di.xml. The default is 20. |
| Which components refresh when the delivery choice or the store changes | Add to the dependentComponents array of DeliveryChoice or LocationList, or remove an entry with xsi:type="null", by the component's name, in a frontend di.xml. |
| Which fields the store's address keeps | Add them to the Magento Inventory inventory_convert_pickup_location fieldset (see Keeping More Fields on the Store's Address). |
| Where the delivery choice sits | Move checkout.delivery-choice in layout XML (see Moving the Delivery Choice). |
| The store dialog's markup | Override Hyva_CheckoutInStorePickup::checkout/shipping/method/pickup/dialog.phtml in your theme. |
Changing the Store Search Term Length
The shortest and longest search term are arguments of the store dialog's Magewire component, LocationList. Lower the minimum to 1 where towns have one-character names, as some do in Japan:
<type name="Hyva\CheckoutInStorePickup\Magewire\Checkout\Shipping\Method\PickupLocation\LocationList">
<arguments>
<!-- Shortest term the store search runs (default 2) -->
<argument name="minSearchTermLength" xsi:type="number">1</argument>
<!-- Longer terms are cut to this length (default 128) -->
<argument name="maxSearchTermLength" xsi:type="number">128</argument>
</arguments>
</type>
The maximum length is also the search field's maxlength, so the browser stops typing where the server would cut the term short.
Moving the Delivery Choice
The delivery choice is declared in hyva_checkout_components.xml as checkout.delivery-choice, inside the shipping details section rather than as a section of its own. That way it travels with the address it governs, including into custom checkouts that the In-Store Pickup module knows nothing about. To place the delivery choice elsewhere, move it in layout XML:
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
<body>
<!-- Place the Ship to me / Pick up in store choice in the guest details section -->
<move element="checkout.delivery-choice" destination="checkout.guest-details.section"/>
</body>
</page>
Do not remove the delivery choice
Removing checkout.delivery-choice makes in-store pickup unreachable, because the shipping method list only offers the methods that belong to the current choice.
Keeping More Fields on the Store's Address
The store's address keeps the fields Magento Inventory copies from the pickup location. To make another field part of the store's address, add it to the to_in_store_pickup_shipping_address aspect of the inventory_convert_pickup_location fieldset, the same way Magento Inventory declares its own fields. This example keeps the pickup location's fax number:
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="urn:magento:framework:DataObject/etc/fieldset.xsd">
<scope id="global">
<fieldset id="inventory_convert_pickup_location">
<!-- Copied from the pickup location onto the pickup shipping address -->
<field name="fax">
<aspect name="to_in_store_pickup_shipping_address"/>
</field>
</fieldset>
</scope>
</config>
How In-Store Pickup Refreshes the Checkout
Moving into or out of collection changes five parts of the checkout that only the server can render. Each refresh costs one Magewire request, because Magewire re-renders a single component per request:
- the shipping method list, because the store picker is the pickup method's own view and renders with it
- the shipping address section, which gives way to the collection notice
- the price summary, because the shipping total and its description belong to the method that was just given up
- the payment methods, which can depend on the shipping address or the order total
- the billing section, which stops offering to reuse the shipping address
Switching between two delivery methods (one courier for another) refreshes none of them. Only moving into or out of collection changes what these components render. Choosing a store refreshes the pickup method, the payment methods and the price summary.
Everything that is a matter of appearance follows the radio button the customer just clicked, in Tailwind CSS: the chosen option through the has-[:checked]: variant, and the "Collection Details" heading through a body-scoped :has() variant. Both change instantly and cost no request, which is why the theme's CSS must be rebuilt after installing.
Related Topics
- Method Auto-Select: The experimental setting that pre-selects the first available shipping method
- Shipping Method Integrations: Other shipping integrations for Hyvä Checkout