Installation booking & Order ID
How a battery and its installation service are bundled into a single order.
Installation booking & Order ID
👤 Ops · 🛠 Dev
When a customer chooses to have their battery professionally fitted, the site has to do something Shopify can't do on its own: reserve an appointment and tie the battery and the labour together so the office can fulfil them as one job. This page explains how.
The flow
Vehicle & battery
The customer's vehicle and chosen battery are already known from vehicle lookup.
Customer details
The customer provides name, contact details, and address (with address autocomplete). Picking an address here also resolves their postcode (suburb, state, eligibility, and installer calendar) - which the next step needs.
Pick a slot
The site loads available appointment slots for the customer's postcode area and they pick one. Availability ultimately comes from that area's Google Calendar. The slot request only fires once a postcode has been resolved - see Scheduling requires a postcode.
Reserve an Order ID
Before anything is added to the cart, the site provisions an Order ID from the booking API and
reserves the chosen slot against it. Behind the scenes the API marks the calendar slot as
[UNCONFIRMED] and stores a pending booking record. This Order ID is the thread that ties
everything together.
Add both items to the cart
Two items are added to the Shopify cart:
- the battery product variant, and
- the installation service product variant.
Both carry the same _Order ID, plus the customer/appointment details as line-item properties.
Pay → the booking is confirmed
When the customer completes checkout and pays, Shopify notifies the API (an order_paid webhook).
Only then is the appointment confirmed - the calendar event becomes a permanent installation,
and confirmation emails go out.
Reserved ≠ confirmed
A reservation only becomes a real booking once the order is paid. If a customer reserves a slot but doesn't complete payment, the API automatically releases the slot back to availability after about an hour. This keeps the calendar from filling up with abandoned checkouts.
A side effect: confirmation depends on Shopify's order_paid webhook reaching the API. If that
webhook is missing or failing, a genuinely paid booking can be released as if it were abandoned -
the customer paid but has no confirmed appointment. See
Common issues.
Returning to an old cart
The booking items stay in the customer's cart long after the one-hour reservation has lapsed, and by then somebody else may have booked the same time.
Once per page view, the theme (assets/booking-check.js) looks for cart items with an _Order ID
and asks the API whether each booking's slot is still available. If a slot has been taken, or no
longer exists, the customer sees a popup listing the affected booking. Both of its buttons remove the
battery and its installation service from the cart, because the items cannot be bought with a time
that is gone:
- Find another slot removes them and sends the customer to the booking page (theme setting Installation booking page).
- Got it removes them and leaves the customer where they are.
Other cart items are left alone. If the check itself fails, nothing is shown.
This does not cover customers who return through the Shop app, whose links go straight to checkout without loading the theme. Those are handled when the payment arrives. See The backend API.
Why the Order ID matters
The Order ID is what links the physical battery to its booked appointment and back to the slot reserved in the calendar. Without it, the office would see a battery and a separate "installation service" line with no way to know they belong together.
The installation service is a real Shopify product. If it is deleted, unpublished, or its variant changes, the second line item can't be added and bookings break. See The installation-service product.
What ends up on the order
Both line items carry properties such as the customer's name, contact, address, the appointment slot and calendar IDs, and the shared Order ID. The battery line names the vehicle; the installation line names the battery to install. The full list is in the line-item property reference.
Delivery-only alternative
Not every customer wants a fitting. The same flow has a delivery-only variant - Buy for delivery - where the battery is shipped and no appointment is booked (so there's no slot reservation or installation-service line). See Page template: Buy for delivery.
For developers
The flow is implemented in assets/installation.js. Key functions: provisioning the order,
reserving the slot (/v1/schedule/reserve), and addBatteryToCart() which posts both items to
cart/add.js. See Custom JavaScript modules.