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).
Pick a slot
The site loads available appointment slots from the booking system and the customer picks one. Availability ultimately comes from the central Google Calendar.
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.
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.