Welcome Shopify Plus merchants! This guide details how to integrate HubBox pickup point services using the official HubBox Local Pickup Shopify App, leveraging the power of Shopify Checkout Extensibility. This approach allows for a seamless integration directly within Shopify's checkout flow, offering flexibility in placement and enabling advanced features.
View HubBox on Shopify App Store
Note: For stores on Basic, Shopify, or Advanced plans, please refer to the Shopify (Basic & Advanced) documentation, as the integration method differs significantly.
The HubBox app utilizes Shopify's Checkout Extensibility framework:
Follow these steps to install the app and perform essential initial configuration.
For the HubBox app to function correctly (specifically, to add identifying tags and pickup details to orders after they are placed), it requires secure access to your Shopify Admin API and a way to receive real-time event notifications via Amazon EventBridge. This is set up by creating a "Custom App" within your Shopify settings.
HubBox Integration
(or similar).read_orders
write_orders
202751687471
Europe (Ireland) eu-west-1
This token is shown only ONCE. Copy it immediately to a secure temporary location (like a password manager or a temporary secure note). Do not save it directly into the HubBox Admin Panel yet. If you navigate away or close the window before copying, you must uninstall and reinstall this custom app to generate a new token.
read/write_orders
permissions.orders/create
, app/uninstalled
).Once the app is installed and your account is licensed by HubBox, you can configure the pickup options.
Admin Panel Option | Set Up |
---|---|
Select Courier Service | Choose which carrier networks (e.g., UPS, DPD, DHL) you want to offer for pickup. |
Change Region | Select the geographic regions/countries where these services should be available. |
Map Settings - Google Maps API Key | Enter your Google Maps API key. This is required to present pickup locations on a map via the HubBox app. |
Map Settings - Map Center Coordinates | Set the location or coordinates for where the map should center by default |
Additional Settings - Shipping rate filter | Turn on for the ability to show and hide shipping rates depending on whether chooses Home Delivery or Pickup option. |
Additional Settings - Pickup options | Select which shipping rates is available to customers who choose a pickup location. |
Additional Settings - Home delivery options | Select which shipping rates is available to customers who choose a pickup location. |
Additional Settings - Orders Token | Input for the orders token created via the custom app in Step 3 |
Additional Settings - Payment methods filter | Install if required to hide pickup option for certain Payment Methods (e.g., Apple Pay, Shop Pay, Klarna, etc.) |
Customization - Discount Code | Set a discount code to be automatically added if customers choose a pickup location. This can be used to encourage customers to use pickup by offering them a discount. |
Customization - Pickup point apperance | Select how pickup UI is presented to customers. Toggles presents pickup and home delivery as 2 radio buttons, Buttons presents pickup and home delivery as 2 buttons, Shipping method presents pickup options as a shipping rate. |
Customization - Pickup options (for Shipping method UI only) | Select which existing shipping rates are used as pickup options. |
Customization - HubBox Carrier Service (for Shipping method UI only) | Create brand new pickup shipping rates via HubBox's Carrier Service. |
Customization - Configure custom shipping method (for Shipping method UI only) | Set the name, price and speed of pickup shipping rates. |
Customization - Local Pickup Shipping Prices (for Toggles and Buttons UI only) | Add the copy to be displayed to customers in the Toggles and Buttons UI. |
Customization - Shipping Method Titles (for Toggles and Buttons UI only) | Add the copy for the titles used in the Toggles and Buttons UI. |
You can choose how the initial pickup option is presented:
Standard App Block (Toggles/Buttons - Default): You add the HubBox App Block via the Checkout Editor (see next section). This block renders UI elements (like toggles or buttons) allowing customers to choose between Home Delivery and Pickup before the shipping rates are shown.
Shipping Rate Method: Configures HubBox to present pickup options as distinct shipping rates within Shopify's standard shipping methods list.
The HubBox app uses Shopify's built-in map component, which requires a Google Maps Platform API key.
Costs: Google Maps API has a generous free tier, but high usage may incur costs. Review Google's pricing.
When using the Toggles or Button launch experience, you may need to filter the shipping rates shown after the customer chooses either Home or Pickup. This is particularly important if you use multiple carrier partners as you will only be able to ship with the same carrier to their network locations.
This functionality utilizes Shopify's Delivery Customizations, which are powered by Shopify Functions.
Note: This filtering is generally not required if using the "Shipping Rate Method" launch experience described above.
This feature allows you to hide specific payment methods from the customer during the final payment step after they have selected a HubBox pickup option for their delivery.
Some express checkout options (like Apple Pay, Amazon Pay, Google Pay) or alternative payment methods might have checkout flows that conflict with or bypass the necessary steps for confirming a pickup location selected earlier. You might also have policy reasons to prefer standard card payments for pickup orders.
When a customer selects a HubBox pickup rate at checkout and proceeds to payment, any payment methods you selected to filter will not be displayed as options.
If using the Shipping Method launch experience, follow these steps to add the HubBox UI to your checkout:
If using the Toggles or Buttons launch experience, follow these steps to add the HubBox UI to your checkout:
Checkout Extensibility allows for powerful validation using Shopify Functions (small backend code snippets deployed to Shopify).
To ensure a smooth customer experience and adherence to logistical constraints, you may need to prevent the HubBox pickup option from being displayed when the customer's shopping cart contains items unsuitable for pickup point delivery. This is crucial for items that exceed carrier size/weight limits, are hazardous, perishable, high-value, restricted, or simply cannot be fulfilled via pickup due to inventory location or other business rules.
For general strategies on what types of products to exclude, please refer to the main Product Eligibility documentation.
With Shopify Plus and Checkout Extensibility, product eligibility is typically managed via a flexible rules engine configured by the HubBox Integrations team within your HubBox account settings. These rules dynamically evaluate the customer's cart and context during checkout. If the conditions for hiding pickup are met, the HubBox app block and/or pickup shipping rates will be automatically hidden ("bailed out") for that specific checkout instance.
Retailers need to clearly define their eligibility criteria (e.g., which product tags, SKUs, collections, weights, prices, countries should exclude pickup) and communicate these requirements to their HubBox Integrations Manager or Client Success Manager. The HubBox team then translates these requirements into specific rules within the HubBox configuration backend.
The configuration generally involves defining one or more Conditions combined by a logical Operator (AND
or OR
) within a bailout
rule.
Each condition typically specifies:
key
: The data point to check (e.g., product tags, cart total, customer country).operator
: The comparison type (e.g., in
, equals
, less than
, greater than
).value
: The value(s) to compare against (e.g., a list of tags, a country code, a price threshold).negate
(Optional): Set to true
to invert the condition (e.g., "NOT equals US").If the combined result of all conditions (respecting the AND
/OR
operator) is true
, the HubBox pickup option is hidden for that checkout.
Below are common ways eligibility rules can be configured by HubBox based on your requirements. These examples show the conceptual structure of the conditions
used:
Use Case: Hide pickup if any product in the cart has one or more specific tags (e.g., "Oversized", "Hazardous", "Pickup-Excluded").
Example conditions
(OR logic):
"conditions": [
{ "key": "|productVariants.product.|tags", "operator": "in", "value": ["Oversized"] },
{ "key": "|productVariants.product.|tags", "operator": "in", "value": ["Hazardous"] },
{ "key": "|productVariants.product.|tags", "operator": "in", "value": ["Pickup-Excluded"] }
],
"operator": "or" // Bail out if ANY condition is true
Note: |productVariants.product.|tags
implies checking tags across all items in the cart.
Use Case: Only offer pickup to customers shipping within specific countries.
Example conditions
(Hide if NOT US):
"conditions": [
{
"key": "customerAddress.countryCode",
"operator": "equals",
"value": "US",
"negate": true // Bail out if country code is NOT US
}
],
"operator": "and" // Only one condition here
Use Case: Only show pickup for US customers AND only if the cart contains a specific enabling tag (e.g., "HubBox-Eligible").
Example conditions
(Hide if NOT US OR if HubBox tag is MISSING):
"conditions": [
{ // Condition 1: Hide if NOT US
"key": "customerAddress.countryCode",
"operator": "equals",
"value": "US",
"negate": true
},
{ // Condition 2: Hide if HubBox tag is MISSING
"key": "|productVariants.product.|tags", // Check tags of items
"operator": "in",
"value": ["HubBox-Eligible"], // The required tag
"negate": true // Bail out if this tag is NOT present on any item
}
],
"operator": "or" // Bail out if EITHER condition is true (Not US OR Missing Tag)
Use Case: Hide pickup for very low value carts (doesn't justify cost) or very high value carts (risk mitigation).
Example conditions
(Hide if subtotal < $50 OR total > $1000):
"conditions": [
{ "key": "cartSubtotalAmount", "operator": "less than", "value": 5000 },
{ "key": "cartTotalAmount", "operator": "greater than", "value": 100000 }
],
"operator": "or"
Note: cartSubtotalAmount
is typically pre-tax/shipping, cartTotalAmount
includes tax/shipping. Values are usually in base currency units, e.g., cents for USD/EUR, pence for GBP. Example uses cents.
Use Case: Limit pickup to single-item orders or carts below a certain item count if box sizes are restrictive.
Example conditions
(Hide if item count >= 3):
"conditions": [
{ "key": "productQuantity", "operator": "greater than or equals", "value": 3 }
],
"operator": "and"
Use Case: Exclude pickup if the cart contains items from specific internal collections (e.g., "Furniture Collection," "Bulky Items Collection"). Requires Collection IDs.
Example conditions
(Hide if ANY item is in Collection A OR Collection B):
"conditions": [
{
"key": "collections.|some.|collectionProducts", // Check if ANY item is in ANY listed collection
"operator": "in",
"value": ["462329577784", "462329545016"] // Your Collection IDs
}
],
"operator": "or"
Note: You can find Collection IDs in the Shopify Admin URL when viewing a collection.
Use Case: Hide pickup if required stock is unavailable at the specific Shopify Location designated for pickup fulfillment (Advanced).
Example conditions
(Hide if ANY item has < 1 stock at Location ID 12345):
"conditions": [
{
"key": "|productVariants.inventoryLevel.12345", // Check inventory for location ID
"operator": "less than",
"value": 1 // Check if available stock is less than 1
}
],
"operator": "or"
Note: This typically checks current available stock, not necessarily if the stock level is sufficient for the quantity requested in the cart. More complex reservation logic usually requires custom Shopify Functions.
Use Case: Exclude based on individual item weight or total cart weight exceeding carrier limits. Values must be in GRAMS.
Example conditions
(Hide if ANY item > 15kg OR total cart > 20kg):
"conditions": [
{
"key": "|productVariants.weight", // Checks weight of individual variants
"operator": "greater than",
"value": 15000 // 15kg in grams
},
{
"key": "cartTotalWeight", // Checks total weight of all items
"operator": "greater than",
"value": 20000 // 20kg in grams
}
],
"operator": "or"
extensionRules.bailout
conditions in your store's backend settings.By leveraging these eligibility rules (configured by HubBox), you can ensure a smoother operational flow and prevent customer frustration by only offering pickup options when appropriate for the items in their cart.
As mentioned in the Configuration section, the HubBox app typically creates a Delivery Customization Function when you configure rate filtering in the app admin for the "App Block" launch experience. If you need more complex filtering logic than the app admin provides, your developers can create/edit this Function directly. It receives cart/destination details and returns a list of shipping rates to hide.
Refer to Shopify Dev Docs for Delivery Customizations.
This feature integrates UPS's DeliveryDefense service, which provides an address confidence score (High, Medium, Low) for US shipments, helping you assess delivery risk.
When enabled, for orders shipping to the US, the HubBox app retrieves the score from UPS and adds it to the Shopify order.
Order Data: Adds specific Tags (e.g., DeliveryDefense risk level: High
, DeliveryDefense risk level: Low
) and Note Attributes (e.g., delivery_defense_score 727
) to the Shopify order.
For more information on this feature and how to set up Access Point shipping rate discount for high-risk home deliveries, please see the DeliveryDefense documentation.
collectPointId
, etc.) present?To access HubBox's UAT guide, visit the Testing Documentation.
When an order is placed using HubBox pickup via the Checkout Extension app:
UPS Access Point
, DPD Ship to Shop
, DHL Parcel Pickup
).collectPointId
(or similar): The unique ID of the chosen location.collectPointNetwork
: The carrier network key (e.g., ups
, dpd
, dhl
).collectPointName
: The name of the pickup location.DeliveryDefenseScore
: Confidence level score, a number between 0-1000 (e.g., delivery_defense_score 727
).DeliveryDefense risk level: High
, DeliveryDefense risk level: Low
).Use this combination of updated shipping address, tags, and note attributes in your fulfillment workflow to correctly identify, manifest, and ship HubBox orders.
For issues during app installation, configuration, testing, or questions about advanced features like Shopify Functions integration on Shopify Plus, please contact the HubBox Client Support or Integrations team at clientsupport@hub-box.com. Provide details, screenshots, and relevant configuration information.