# GEO Agent Shopify Billing Verification

Use this when verifying the billing path before Shopify App Store review submission.

## Billing Contract

- App charges use Shopify Billing subscriptions only.
- The public commerce, agent, catalog, quote, checkout, OpenAPI, and static API index surfaces must not advertise direct Stripe, Payment Link, SPT, x402, direct card checkout, or other off-platform app charges.
- `/app/billing` creates the Shopify subscription approval URL through `appSubscriptionCreate`.
- The billing return URL must be an absolute `https://geo-agent.fly.dev/app/billing/callback` URL with Shopify shop, host, and embedded context preserved when present.
- `/app/billing/callback` updates the merchant's local plan only after Shopify reports a matching approved active subscription through `currentAppInstallation.activeSubscriptions`.

## Reviewer Flow

1. Install GEO Agent from the Shopify review or Admin install surface.
2. Open the embedded app and choose a plan from Billing or Settings.
3. Confirm Shopify shows its subscription approval screen.
4. Approve the subscription in Shopify.
5. Confirm Shopify returns to the embedded app.
6. Confirm the app reflects the approved plan only after Shopify reports an active subscription.

## August 13, 2026 Review Fix

Shopify reported that the subscription approval page was being opened inside the embedded Admin iframe, where `admin.shopify.com` refused to connect. The billing route now uses the authenticated Shopify Remix redirect helper with `target: "_top"`. This invokes the App Bridge escape path for embedded requests and opens Shopify's confirmation URL in the top-level Admin context instead of inside the app iframe.

Verification completed against the deployed production revision:

- The billing fix was first deployed and verified healthy on Fly machine version `190`; subsequent deployments retain the same tested redirect.
- The full Vitest suite passes: 12 files and 146 tests.
- The production Remix build succeeds.
- Shopify Theme Check passes with 2 extension files inspected and no offenses.
- The billing redirect regression test asserts use of Shopify's authenticated redirect helper and the top-level redirect target.
- The production review smoke suite passes all public, OAuth, API, and webhook checks.

## Expected Direct-Origin Behavior

Agent-readable checkout calls at `https://geo-agent.fly.dev/api/v1/checkout` are not a direct payment checkout. They return Shopify Billing guidance and point merchants back to Shopify-owned install and billing approval surfaces.

## Guardrails

- Do not use `charge_id` alone as proof that billing was approved.
- Do not reintroduce direct Stripe Payment Link, SPT, x402, direct card checkout, or machine-payment language into app-review-facing surfaces.
- Do not put pricing in screenshot captions or marketing screenshots. Pricing belongs in Shopify's pricing details section and the in-app billing context.