App Proxy for custom themes

The Theme App Blocks approach works for any Online Store 2.0 theme. For vintage themes, headless storefronts, or fully custom theme builds, you use the App Proxy instead. The capability is the same; the integration surface is different.

What the App Proxy does

The App Proxy gives the merchant a stable, HMAC-signed URL under their own domain (/apps/orderwise/...) that forwards to OrderWise. Requests that come through the proxy are pre-authenticated — Shopify signs them with the merchant's app secret, and OrderWise verifies the signature before doing anything.

This means a custom theme can call OrderWise endpoints without exposing the merchant's API key, without CORS issues, and without the customer needing a separate session.

Two endpoints worth knowing

Two proxy endpoints cover the majority of custom-theme integrations:

• /apps/orderwise/order-lookup — given a customer email and an order reference, returns the order summary the AI would use. Useful for rendering a self-service status page on a custom storefront.
• /apps/orderwise/faq — returns the merchant's knowledge base as JSON, scoped by locale and optional category filter. Useful for rendering a custom FAQ section.

Both endpoints respect the same auto-execution rules and locale detection that the embedded widget uses, so the responses are consistent across surfaces.

HMAC verification

OrderWise verifies the signature query parameter on every proxy request using the merchant's shared secret. Requests that fail verification are rejected with a 401. The merchant doesn't have to do anything to make this work — Shopify signs the request, OrderWise verifies the signature.

If a custom theme is calling the proxy and getting 401s, the most common cause is the storefront stripping query parameters during a redirect. Make sure the request hits the proxy URL directly without an intermediate redirect.

When to use the storefront widget instead

The App Proxy is for surfaces where the merchant wants the OrderWise data inline in their own UI. If they want the standard chat widget floating in the corner, install it via the standard widget script tag — the App Proxy is overkill for that use case.