The problem

OTO aggregates hundreds of delivery providers across the Gulf. Its delivery-fee endpoint authenticates with a long-lived refresh token exchanged for a short-lived access token. A Shopify theme is public JavaScript — anything the cart page can read, a customer can read — so calling OTO from the storefront would have published the account's credentials.

The alternative was what the store was already doing: leave shipping until checkout, and lose the carts that were price-sensitive about it.

What I built

A small Express service on Railway between the storefront and OTO, exposing one public endpoint: POST /api/shipping-estimate, taking a destination city, a chargeable weight and an optional order total. It returns a flat list of carrier options with price, ETA and logo.

Everything sensitive stays server-side. The refresh token lives only in Railway's environment — never in the repo, a commit, or a log line. The service exchanges it for a one-hour access token, caches it in memory, refreshes proactively around the 55-minute mark, and retries once if OTO returns a 401 or 403 mid-request.

The parts that matter in production

• CORS allow-list so only the store's own domains can call the endpoint.
• Two layers of rate limiting — 30 estimate requests a minute, plus a 120/min baseline across all routes, health check exempt.
• Short response cache, because ten shoppers in Riyadh with a two-kilo cart should not be ten calls to OTO.
• Timeouts and bounded retries upstream, so a slow carrier API degrades into a missing estimate rather than a hanging cart.
• Weight ceiling validated before the upstream call.
• Mock mode returning canned carrier data with no token, so the widget can be built locally without touching production credentials.

The cart side

The widget renders from the cart footer section. It reads /cart.js, converts line-item grams into a chargeable weight in kilograms, and posts that with the selected city. Carrier rows render with price, estimated window and — deliberately — the cash-on-delivery surcharge as a separate note rather than folded into the headline number.

Where it stops

The estimate is display-only and labelled that way. Shopify still calculates and charges its own rate at checkout; this shows an indicative cost early, at the moment it decides whether the cart survives.

Architecture

Three services on Railway: a Claude-driven agent server holding the conversation, an MCP tool server exposing catalogue and cart operations as tools, and a storefront service talking to Shopify. Splitting the tool layer out of the agent is why search could be rewritten several times without touching conversation handling.

Search on a catalogue this size

The first version asked the model to guess — which fails the moment a buyer types a partial SKU shared by four hundred other parts. I rebuilt search to query the Storefront API directly with a strategy: broad full-catalogue query first, an intelligent retry on a simplified query, then a multi-level fallback. SKU-shaped input is detected and ranked by exact match; a brand name in the query infers a vendor filter. The same pass deleted a redundant search layer and unnecessary API calls that were adding latency to every message.

The production-only failures

• A Storefront token 401 loop. Token logic had been written against a legacy OAuth flow. Rebuilt on the official Admin REST flow with proper refresh and validation, which also cleared the cart failures and domain leakage behind it.
• Shopify blocking the app as a security threat. Reconfiguring the proxy and correcting the request path cleared every security error.
• Cart operations failing silently. Add to cart and checkout now run inside the chat with token refresh and validation on each call.

Conversation and interface

Session handling covers new chat, end chat, history hydration without duplicate threads, and email capture so a conversation that doesn't convert still becomes a lead. Product results render as a carousel with a modal detail view; the input auto-expands; a multi-phase indicator shows what the agent is doing rather than spinning at the user.

Later I upgraded the Claude model and rewrote the system prompts for cleaner tool queries and better instruction-following, which noticeably reduced empty and incorrect results on multilingual and ambiguous questions — a real requirement for a Gulf storefront.

The structural decision

Two hundred thousand products can't be organised by hand, and a catalogue that grows every month can't be organised by template. So the category structure lives in data: every collection carries a custom.parent_collection metafield, and the theme walks that chain to render subcategory cards, breadcrumbs and filters.

That one decision is why 270 collection pages and 120 new subcategories could be added from a forty-thousand-product file without a new template, and why breadcrumbs across the store auto-generate the deepest correct path with zero per-product setup.

Finding things

Metafield-based filters run across 200+ collection pages with Rapid Search. Getting there meant diagnosing filter-definition conflicts with both Shopify and Rapid Search support, and securing a custom plan sized for a 200k-product limit. The AODD pump range shows what the structure buys: sixty-plus collection pages across size, material and diaphragm variant, all with working filters, breadcrumbs and mega-menu entries.

The unglamorous half

• Import. ~40,000 products loaded file by file to avoid duplicates. Broken imagery traced to CSV links pointing at unstable Google PageSpeed URLs — 4,974 corrected and re-imported via Matrixify.
• Pre-orders. Cart drawer replaced with a dedicated cart page: pre-order buttons, stock badges and counts, and a warning that fires only on mixed carts.
• Product pages. Larger specifications panel, SKU + brand line linking to the vendor collection, tariffs & fees tab, bigger imagery, direct route to a specialist.
• SEO. One H1 per template, ALT text across 270+ collection pages, content on ten IFM collection pages, related products from the deepest assigned collection.
• Measurement. PostHog across the site where previously there was nothing to look at.

What came out of it

A second storefront for Saudi Arabia launched from the same theme in May 2026 with regional details, a dual-office footer, redirects disabled so Saudi clicks stay on the Saudi site, and its own distributor landing page. A structure built to be reused turned out to be reusable.