Cart & checkout

Rentshelf uses standard Shopify orders for every booking. The product picker, cart helper and order webhooks carry rental context through Shopify without replacing checkout.

Here’s the full journey.

1. On the product page

The rental picker collects:

Dates (start, end) and duration (days)
Duration mode (flexible range, fixed package, hourly or variant duration)
Add-ons selected + quantities
Booking deposit or security deposit (if applicable)
Payment option (deposit today or pay in full, when both are enabled)
Delivery method and customer inputs

When the customer clicks Add to cart, the picker submits a standard form action="/cart/add" with:

Variant ID — the first (or selected) variant of the product
Quantity — set according to the active duration mode. Flexible daily rentals may use days; package, hourly and deposit flows can use a fixed line quantity while rental metadata carries the authoritative quote.
Line-item properties — rental metadata (see below)

2. Line-item properties

Rentshelf adds these properties to the cart line:

Visible (shown to the customer in cart and email)

Property	Example
`Rental pickup`	`2026-10-14`
`Rental return`	`2026-10-17`
`Rental duration`	`3 days`
`Rental quote`	`$45.00`
`Selected add-ons`	`Insurance (qty 1)`
`Due today`	`$55.00` (only if deposit > 0)
`Remaining balance`	`$55.00` (booking deposits only)
`Payment option`	`Pay deposit today` or `Pay in full`
`Delivery method`	`Courier delivery`
`Rental notes`	(only if the product has a notes field)

Internal (prefixed with `_`, hidden from the customer by Shopify)

Property	Purpose
`_rental_start`	Canonical start date (ISO)
`_rental_end`	Canonical end date (ISO)
`_rental_days`	Duration in days
`_rental_total`	Authoritative total
`_rental_deposit`	Deposit amount
`_rental_due_today`	Amount that should be charged today
`_rental_remaining_balance`	Balance due after checkout
`_rental_payment_option`	Deposit or pay-in-full choice
`_rental_addons`	JSON blob of picked add-ons
`_rental_currency`	Currency at booking time

The webhook handler parses both visible and internal properties to build the final Booking record — visible properties are a human-friendly mirror for the cart UI and emails.

3. In the cart

Rentshelf’s JS runs on the cart page to:

Hide the product’s normal sale price for Rentshelf-connected rental lines.
Rewrite the displayed line total using the rental quote or due-today amount.
Keep subtotal aligned with the rental line total so customers do not see a mismatch between cart total and checkout total.
Sync the line quantity to the stored _rental_days if the cart was loaded from a session with a different days.
Add cart-level note attributes summarising rentals in the cart (Rental window, Rental total).
Call /apps/rental/reserve to create a CHECKOUT / PENDING booking as a soft hold on the dates. This prevents two customers from both checking out the same rental at the same time.

The hold expires if the order isn’t placed within 60 minutes.

4. At checkout

Shopify’s native checkout runs. Taxes, shipping, discounts and payment gateways all work as normal.

For booking deposits, the checkout total is the due today amount. The full rental quote and remaining balance are stored on the booking and order metadata for follow-up.

If automatic remaining-balance collection is enabled, Rentshelf can create a Shopify draft order payment link when the balance becomes due. This requires the draft orders permission.

5. When the order is placed

The orders/create webhook fires. Rentshelf:

Reads the line-item properties from the order payload.
Rebuilds the Booking from properties (authoritative — the internal _rental_* properties win over the visible ones in case of any drift).
Links the booking to the Shopify order (orderId, orderName).
Sets booking status based on order payment status:
- PAID → CONFIRMED
- PENDING (manual) / PARTIALLY_PAID → PENDING
Adds an order tag rental and attaches order attributes (Rental booking, Rental window, Rental total).
Stores deposit, due-today, remaining-balance, payment option, delivery method and customer input details.
Cleans up any duplicate CHECKOUT bookings created during the hold phase.

6. When the order is cancelled

The orders/cancelled webhook fires and related bookings move to CANCELLED. Dates immediately free up.

Refunds

Use Shopify’s native refund flow. Rentshelf doesn’t intercept refunds — refunding the rental line is the merchant’s choice (e.g. return fees, damage deductions).

The booking record is not automatically cancelled on refund. This is intentional — a partial refund might mean the rental still happened, you’re just compensating the customer. Cancel the booking manually from Rentshelf → Bookings if the rental isn’t going ahead.

Known limitations

Cart theme support matters. If a theme strips line-item properties or overrides cart totals aggressively, test on Dawn or the Rentshelf demo theme to isolate the issue.
Discounts need testing with deposits. Shopify discounts apply to the checkout amount, so confirm discount behavior for deposit-only and pay-in-full flows.
Gift cards work normally — they apply to the amount collected at checkout.
Local pickup / delivery rates work normally. Shipping rates are computed from the checkout total as usual.

App proxy endpoints — the reserve, config and quote endpoints used by the storefront picker.
Webhooks & data — how orders sync into bookings.
Returns workflow — how completed rentals are chased, returned and printed.