WWooshPayment docs
Store integration

Shopify integration

Connect Shopify to WooshPayment via OAuth Public App. ScriptTag auto-installed, orders synced, minimal scopes.

3 min read

The Shopify integration uses an OAuth Public App to read the catalog, create orders, and install a ScriptTag that intercepts the "Checkout" button and redirects it to your WooshPayment checkout.

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 → domain form → "Connect".

B) From Settings — Dashboard → Settings → Shopify connection → enter your your-store.myshopify.com → "Start OAuth".

Backend internals (for those who want to understand):

  1. The form does POST /api/auth/shopify/install with shopDomain + a JWT handoff token (your current session)
  2. We receive the Shopify OAuth URL and redirect you there
  3. You authorize on your store 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 automatically
  7. We send you back to the dashboard with shopifyConnected: true

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)

No copy/paste into the theme, no changes to theme.liquid. When you uninstall the app from Shopify, the ScriptTag is removed automatically.

4. Verify it works

  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/...
  5. Complete a pilot order with the Whop test card 4242 4242 4242 4242
  6. Verify that the order also appears in Shopify Admin → Orders with the WooshPayment tag and payment_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 payment_status: paid
  4. Shopify decrements inventory and the standard fulfillment flow starts
  5. The "order confirmed" email to the customer is sent by Shopify, not us
  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 shopifyOrderId is empty, 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