WWooshPayment docs
Store integration

Shopify integration

Connect Shopify to WooshPayment with Dev Dashboard + OAuth. ScriptTag installed, live cart test required, orders synced, minimal scopes.

4 min read

The Shopify integration uses a dev app created in your Shopify Dev Dashboard plus OAuth. You paste Client ID + Client Secret into WooshPayment, authorize the app in your Shopify admin, and we install the ScriptTag that intercepts the "Checkout" button and redirects it to your WooshPayment checkout when the theme loads it correctly.

Before sending traffic, always run a real cart test on the live theme. ScriptTag is Shopify's legacy path: modern, custom or headless themes can require support or a dedicated app embed if they do not load the script.

For the current click-by-click path, use the full guide: Connect Shopify with Dev Dashboard + OAuth.

Requirements

  • Active Shopify store (any plan)
  • Admin permissions on the store
  • WooshPayment account (see Quickstart)

1. Start the integration

There are two entry points:

A) From onboarding — at first login, "Platform" step → choose Shopify → create the dev app following the instructions → paste domain, Client ID and Client Secret → "Connect store".

B) From Settings — Dashboard → Settings → Shopify connection → paste domain, Client ID and Client Secret → "Open Shopify authorization".

Backend internals (for those who want to understand):

  1. The form does POST /api/merchant/shopify/connect-dev with Shopify domain, Client ID and Client Secret
  2. We save the credentials encrypted and receive the Shopify OAuth URL
  3. We redirect you to Shopify, where you authorize the app in your admin
  4. Shopify sends us back to the callback, we exchange the code for accessToken
  5. We encrypt the accessToken (AES-256-GCM) and save it associated with your merchant
  6. We install the ScriptTag and checkout health is verified
  7. We send you back to the dashboard with shopifyConnected: true: this means OAuth is authorized, not that traffic is certified. Before traffic you still need an active plan, Whop/COD readiness and a real live-cart test.

2. Required OAuth scopes

ScopeWhat it's for
read_productsRead titles, prices, variants, images for the checkout
read_orders / write_ordersCreate the order on your Shopify after confirmed payment
read_checkouts / write_checkoutsManage the checkout session
read_customersAuto-fill address for already-registered customers
read_script_tags / write_script_tagsInstall/update the redirect ScriptTag

No write_products or write_customers permission. WooshPayment reads your catalog and your customers but never modifies them.

3. The ScriptTag

Installed automatically at the OAuth callback. When a customer clicks "Checkout" from the Shopify cart:

  1. The script intercepts the click before the native redirect
  2. It captures the cart (line items + total + currency)
  3. It calls POST /api/checkout/create (WooshPayment)
  4. It redirects to https://{your-slug}.wooshpayment.com/checkout/{token} (or checkout.yourdomain.com if you've mapped a custom domain)

In the standard path you do not paste code into the theme. The deciding check is still the real cart on the published theme: if the click stays on Shopify checkout, do not send traffic and use Script tag debug or support for app embed/custom validation. When you uninstall the app from Shopify, the ScriptTag is removed automatically.

4. Verify it works

This verification is mandatory even if the dashboard shows the ScriptTag as present.

  1. Open your store in an incognito window (to bypass cache + cookies)
  2. Add a product to the cart
  3. Click "Check out"
  4. You must land on {your-slug}.wooshpayment.com/checkout/...; if you stay on Shopify checkout, the live theme is not traffic-ready
  5. Complete a paid pilot order with a small real amount or a Whop sandbox explicitly enabled by support
  6. Verify that the order also appears in Shopify Admin → Orders with the WooshPayment tag and financial_status: paid

5. What happens after payment

  1. Whop sends an invoice_paid or membership_activated webhook to https://api.wooshpayment.com/webhooks/whop/payment-update (HMAC-SHA256 signed)
  2. WooshPayment marks the session COMPLETED
  3. We call Shopify's Orders API to create the real order with financial_status: paid
  4. Shopify decrements inventory and the standard fulfillment flow starts
  5. The "order confirmed" email to the customer is sent by WooshPayment, branded with the store name and with Shopify receipt disabled to avoid duplicates
  6. WooshPayment sends the merchant a notification via Resend (noreply@wooshpayment.com)

Common errors

Right after OAuth the dashboard says "Not connected"

Known stale localStorage bug. Solution: refresh the page with Cmd+Shift+R. The store does refreshMerchant() on mount and recovers the correct state.

ScriptTag doesn't appear installed

Go to Shopify Admin → Apps → WooshPayment. If the app is there but the Checkout button doesn't redirect:

  1. Hard refresh the store (Cmd+Shift+R) to clear the JS cache
  2. If it persists: uninstall the app from Shopify, return to WooshPayment and restart OAuth from Settings
  3. If still nothing: Script tag debug

Orders not created in Shopify

The order appears in WooshPayment but not in Shopify:

  • Check in Dashboard → Orders the status of the session. If it is COMPLETED but Store order is missing, the issue is the Orders API call
  • Check that the write_orders scope is still active: sometimes a partial uninstall/reinstall leaves old scopes
  • Quick fix: disconnect and re-authorize from Settings

"Invalid cart" on the customer side

Most likely the product prices changed between add-to-cart and checkout. The customer should refresh the cart.

Uninstalling

  1. Shopify Admin → Apps → WooshPayment → Uninstall — revokes permissions, ScriptTag removed
  2. In WooshPayment the Shopify status becomes "Not connected"; the merchant remains but can no longer create orders on your store

Next steps