Skip to main content

Delivery Customization Functions

A delivery_customization function modifies the merchant’s existing shipping zones before they render at checkout. Use it to add delivery dates to a zone name, hide a zone for some addresses, or pin a free zone to the top of the list. To add a brand-new rate, use Shipping Rate Functions. To filter built-in zones, use this one. Runs at both cart verification (preview) and order placement (enforcement). A stale frontend that submits a hidden zone is rejected server-side with:
"Shipping option '<zone-name>' is not available for this order"

How It Works

Function Manifest

Input Schema

The deliveryOptions list contains only merchant-configured shipping zones — not the app rates added by shipping_rate functions. To customise an app rate, return it differently from your shipping_rate function in the first place.

Output Schema

Either handle (zone UUID) or deliveryOption (zone name) works as the matcher — the backend checks both fields for every op. On a move op, index is accepted as an alias for position (either field works).
reorder is accepted as an alias for move — both produce the same result. New code should use move.

Examples

Add delivery date to the name

Hide express on weekends

Pin the cheapest to position 0

Free-shipping nudge

How it renders in the UI

The checkout shipping step reads the deliveryCustomizations returned by cart verification and applies hide/rename ops before rendering the radio list. Reorder is honoured the same way.

Best Practices

With no shipping zone visible, the customer can’t place the order. Always leave one zone reachable, or pair the hide with a clear error in an order_validation function.
deliveryOption (the name) works but merchants can rename their zones — handle doesn’t change.
Long names wrap badly on mobile checkout. 1–2 lines max.
Drive /checkout with Puppeteer and screenshot the shipping radio. The hide/rename/reorder flow is wired through the checkout UI — JSON-only tests miss that path.

See Also