Skip to content
Cobalz Affiliate

Shopify integration

Connect a Shopify store through OAuth. Cobalz subscribes to orders/create, orders/updated, refunds/create, and app/uninstalled webhooks. Tokens live in Supabase Vault per-merchant.

Install

  • From your merchant dashboard: Settings → Store connection → Install Shopify.
  • You land on Shopify's OAuth consent page. Approve the requested scopes (read_orders, read_customers, read_price_rules, write_price_rules).
  • Shopify redirects back to /api/shopify/oauth/callback. We verify the HMAC + CSRF state, save the token to Vault, register webhooks, redirect to your dashboard.

Webhook contract

All inbound webhooks land at /api/shopify/webhook/<merchant_id>. We verify the X-Shopify-Hmac-Sha256 header against the per-app secret, confirm X-Shopify-Shop-Domain matches the merchant's canonical shop domain (defence against the multi-tenant takeover where any other shop on the same app could POST a HMAC-valid webhook), and dedupe via webhook_events.

Required env vars

  • SHOPIFY_API_KEY, SHOPIFY_API_SECRET — from your Shopify Partners app.
  • SHOPIFY_APP_SCOPES — comma-separated scope list.
  • SHOPIFY_REDIRECT_URI — must match the URI registered in Partners.
Note:Auto-coupon on approval: when you approve a Shopify-store affiliate, we create a personal price rule via POST /price_rules + POST /discount_codes and stamp it on the affiliate's coupon list. Toggle off at Settings → Affiliates → Auto-coupon.