Shopify fit, availability, and setup

Proxy for Shopify turns a supported storefront cart into a shareable Proxy handoff. The payer reviews the request through Proxy, then completes the purchase in native Shopify Checkout.

Shopify remains the checkout and payment processor. Proxy does not add a payment method, collect card data, or replace Shopify Checkout.

Public self-serve installation is not available yet

Use Shopify only if Proxy has given your organization an approved Shopify review or install link. If you do not have that link, stop here: do not create a custom app, paste an Admin token, or install the server SDK as a workaround. Use the Stripe path chooser for a non-Shopify checkout, or ask your existing Proxy contact to confirm access before planning a Shopify launch.

Is Shopify the right provider?

Choose Shopify when all of these are true:

• the buyer starts from a Shopify storefront cart;
• the final order must be created and paid in Shopify Checkout;
• your published theme can enable the Proxy app embed for a supported cart drawer or full cart page; and
• Proxy has approved the shop and supplied the Shopify-managed review/install route.

Choose Stripe instead when your application owns the cart outside Shopify or already sends the payer to a Stripe payment flow.

Before you start

You need:

• Shopify administrator access for the shop;
• the approved Proxy review/install link for that shop;
• a Proxy account with access to the organization and merchant that should own the connection;
• a theme with a supported cart page; and
• permission to place a test order.

The Proxy Checkout public app is the normal integration. The @proxy-checkout/shopify-server-js package contains lower-level server primitives used by the app; it is not a self-serve alternative to installation, OAuth, merchant linking, or app review.

Install and link the shop

1. Open the approved Shopify review/install link supplied by Proxy. If you do not have a link, do not continue.
2. Install Proxy Checkout. Shopify starts the authorization flow; Proxy never asks you to paste a shop domain or Admin token.
3. Open the embedded Proxy Checkout app. Choose Connect Proxy, then sign in or create a Proxy account.
4. Select the Proxy organization and merchant that owns the shop. The connection link is one-use and expires. A shop already linked to another merchant cannot be claimed.
5. Choose Choose Shopify plan in the embedded app and approve Proxy’s usage-based plan in Shopify. Wait until the app reports Shopify pricing is active. Checkout and theme setup remain blocked while the plan is missing, unavailable, or does not match the required usage meters.
6. Follow Enable storefront action into the Shopify theme editor. Enable the Proxy app embed in the published theme so the delegated-payment action appears below native checkout actions in supported cart drawers and on the full cart page.

Validate before launch

1. Confirm the embedded app shows the Proxy merchant connected, Shopify pricing is active, and the storefront action enabled on the published theme.
2. Build a supported cart with at least one purchasable variant.
3. Start one Proxy handoff from the cart action and open it as the payer.
4. Confirm Proxy shows the expected requested cart and latest Shopify estimate.
5. Continue to Shopify Checkout and place a Shopify test Order.
6. Confirm the final Order is correlated to the same Proxy session and the merchant receives the expected signed events.
7. Confirm your fulfillment or entitlement handler processes the Order once, even when events are retried.

You know the connection works when one source cart produces one Proxy handoff, the payer reaches native Shopify Checkout, and one authoritative Shopify Order drives one idempotent merchant outcome.

Continue with Entitlements if payment grants access. Review the pricing and checkout semantics below before making the cart action available to customers.

Pricing

The Shopify plan has a $0 monthly base price and two usage charges for each eligible Order:

• $0.30 per Order; and
• 3% of the Order’s placement-time, pre-discount merchandise subtotal.

An Order becomes eligible when Shopify first reports a positive, successful SALE or CAPTURE transaction. Proxy submits the usage charges once per Order at that point, including when the first capture is only a partial payment. Later captures do not duplicate the charges. Full payment is still required before the Order can be finalized and provisioned.

Shopify test Orders and Orders with no positive payment are not charged. Gift-card products and payment with gift-card value do not exempt an otherwise eligible Order; gift-card issuance and later redemption are evaluated separately when Shopify represents them as separate Orders. If a cart’s merchandise is fully discounted but the Order has a positive payment, such as paid shipping, the percentage charge still uses the pre-discount merchandise subtotal. Initial subscription Orders and eligible renewals are evaluated separately.

Proxy currently supports App Pricing currencies with two decimal places. The App Pricing currency must match a complete Shopify Order money amount; Proxy does not silently convert currencies. Shopify’s App Pricing terms apply, including any Shopify processing fee, tax, or revenue share.

A buyer refund does not automatically reverse the Proxy usage charge.

What happens during checkout

Each handoff uses a dedicated Shopify Storefront Cart. It does not reuse the shopper’s browsing cart.

1. The theme action reads the Shopify cart’s variant IDs, quantities, selling-plan IDs, and supported string line properties.
2. Proxy validates the shop, installation, cart contents, and request. Titles, prices, totals, and currency supplied by the browser are not trusted.
3. Shopify creates a Storefront Cart and Proxy creates the shareable handoff.
4. The payer reviews the latest estimated total in Proxy. When they continue, Proxy retrieves a fresh Shopify checkout URL.
5. Shopify Checkout presents the final shipping, tax, discounts, currency, gift-card contribution, and inventory availability for approval.
6. After payment, Proxy reconciles the authoritative Shopify Order and updates the session and merchant events. A changed total is recorded as a visible difference rather than silently replacing the requested amount.

The final approval is in Shopify

Proxy shows who requested the purchase and the latest estimate. Shopify Checkout shows the final total and availability before the payer submits payment.

Requested estimate and final Order

Shopify treats Storefront Cart cost as an estimate. Proxy therefore uses provider_finalized pricing and keeps three values separate:

• Requested is the customer’s normalized source cart and initial estimate.
• Latest estimate is the Shopify Cart total retrieved immediately before redirecting the payer.
• Final is the authoritative Shopify Order amount after payment.

Shipping, tax, automatic discounts, Shopify Markets currency, inventory changes, gift cards, and supported line transformations can change the final result. Proxy accepts the final Order only when it can correlate that Order to the exact merchant, shop, installation, handoff, and Shopify Cart.

Supported cart behavior

The Shopify integration supports:

• Shopify product variants with positive integer quantities;
• up to 250 cart lines per handoff;
• safe string line properties;
• automatic discounts recalculated by Shopify;
• native shipping and tax selection;
• Shopify Markets and presentment currency;
• Shopify inventory checks, cart transformations, and warnings;
• gift-card payments and zero- or split-tender outcomes;
• selling-plan IDs for the initial checkout; and
• repeat one-off purchases through new Proxy handoffs.

The theme cart and the Storefront Cart are separate Shopify objects. Proxy rejects a source cart it cannot represent and returns an actionable reason. Do not assume a handoff will preserve:

• remote products;
• a discount code held only in theme state;
• a signed-in Shopify Customer or B2B identity;
• a previously selected delivery option; or
• another app’s private or structured line data.

Shopify may reject or change a line when inventory, catalog, selling-plan, or cart-transformation state changes.

Refunds, order changes, and fulfillment

Merchants initiate buyer refunds and fulfillment in Shopify. Proxy observes the resulting Shopify data; it does not call Shopify’s refund or fulfillment actions.

A Shopify Refund record alone does not prove that money moved. Proxy changes payment state only after Shopify reports a successful refund transaction. Successful refunds below the original paid amount are partial; successful refunds at or above that amount are full. Pending and failed refund transactions remain visible without changing the payment state.

Order edits, cancellation, or additional collection after payment do not rewrite the original payment evidence. Proxy records the changed Order and may mark the session as requiring merchant action. Do not retry the payment when successful payment evidence is already present; make any commerce correction in Shopify.

Fulfillment is independent of payment and Proxy provisioning. Proxy can report split, partial, held, scheduled, moved, completed, and cancelled fulfillment facts. Those updates do not mark a Proxy session as provisioned; the merchant’s explicit provisioning acknowledgement remains authoritative.

Proxy exposes the observed lifecycle through merchant events:

• payment_attempt.partially_refunded and payment_attempt.refunded for the initial Order;
• shopify.refund_observed when refund evidence arrives while the initial payment attempt still requires reconciliation;
• shopify.subscription_payment_observed and shopify.subscription_refund_observed for an eligible renewal and its refund; and
• shopify.fulfillment_observed for fulfillment changes.

These events report Shopify facts. They do not initiate a refund, provision a Proxy session, or make Proxy the owner of a Shopify Subscription Contract.

Subscriptions and repeat purchases

Each repeat one-off purchase uses a new Shopify Cart and Proxy handoff. Shopify can still reuse its normal customer and Shop Pay experience.

Selling-plan lines can pass through the initial checkout. Proxy records the plan in its estimate and final evidence, but it does not own or manage Shopify Subscription Contracts, recurring billing attempts, retries, cancellation, or customer portals. PRE_ORDER, TRY_BEFORE_YOU_BUY, and OTHER selling-plan categories are supported only for the initial checkout.

For SUBSCRIPTION plans, Proxy recognizes a renewal only when Shopify can verify that it belongs to the same subscription lineage and creator app as the original Order. Each verified renewal is priced as a separate Order when Shopify first reports a positive successful capture. Added one-time items are included in that Order’s merchandise subtotal.

If Shopify cannot provide clear creator and lineage evidence, Proxy retains the Order for reconciliation but does not emit a subscription lifecycle event or submit a usage charge until eligibility is confirmed.

Privacy, tokens, and uninstall

The app requests the minimum Shopify scopes and Protected Customer Data Level 1. Proxy does not request or persist customer name, email, phone number, billing address, or shipping address for this integration. Shopify webhook bodies are treated as short-lived notifications; Proxy reads only the Shopify Order data needed to reconcile the handoff.

The full Storefront Cart ID contains a secret key. Proxy encrypts it with short retention and does not expose it in logs, analytics, merchant events, or API responses. Checkout URLs are retrieved only when the payer is ready to continue.

Shopify access and refresh tokens are stored encrypted. Proxy handles app/uninstalled, app/scopes_update, customers/data_request, customers/redact, and shop/redact. Uninstall immediately blocks new handoffs, cancels work whose checkout was never exposed, and destroys stored token and Cart secrets.

Shopify also removes app access and webhooks on uninstall. If a payer completes an already-open checkout after uninstall, reinstall the app to let Proxy attempt reconciliation. Proxy searches a bounded window of up to 24 hours; an older Order may require manual reconciliation.

Merchant event and API model

Session and Order reads expose the requested, latest estimated, and final amounts separately:

{
  "pricing_mode": "provider_finalized",
  "requested": {
    "amount_minor": 4200,
    "currency": "usd",
    "cart": { "kind": "shopify_storefront_cart_v1" }
  },
  "latest_quote": {
    "amount_minor": 4874,
    "currency": "usd",
    "quoted_at": "2026-07-11T22:00:00Z"
  },
  "final": {
    "amount_minor": 5126,
    "currency": "usd",
    "finalized_at": "2026-07-11T22:04:00Z"
  }
}

Payment attempts use the successful final presentment amount. Shopify evidence retains shop money and successful transaction components separately. Zero-total Orders use the explicit no-payment-required path rather than creating a positive payment attempt.