Shopify ↔ Base44 Integration Bridge
Full referral-to-commission pipeline — hand this doc to your builder or paste into your build workflow.
🚀 Priority Build Order (Fastest to Live)
Capture affiliate ref from URL
Store ref param in localStorage/cookie on landing
Pass affiliate_ref + base44_user_id into Shopify checkout
Use Shopify cart attributes or note fields
Receive orders/paid webhook from Shopify
Create a Base44 backend function as the webhook endpoint
Create pending commission record in Base44
Write to CommissionPayout entity, status = pending
Admin reviews & approves payouts
Use existing AdminCommissionPayout page to process
1. Referral Capture (Frontend)
On any landing page (Landing.jsx, WolfBeansStore.jsx), capture and persist the ref param:
Paste in useEffect on landing pages
useEffect(() => {
const params = new URLSearchParams(window.location.search);
const ref = params.get('ref');
if (ref) {
localStorage.setItem('affiliate_ref', ref);
sessionStorage.setItem('referral_code', ref);
}
}, []);2. Shopify Checkout Metadata
When redirecting to Shopify checkout, append the affiliate ref and Base44 user ID as cart note or URL params:
Shopify checkout URL with affiliate data
const affiliateRef = localStorage.getItem('affiliate_ref');
const base44UserId = user?.id;
const checkoutUrl = new URL('https://wolfbeans.myshopify.com/checkout');
if (affiliateRef) checkoutUrl.searchParams.set('ref', affiliateRef);
if (base44UserId) checkoutUrl.searchParams.set('b44uid', base44UserId);
window.location.href = checkoutUrl.toString();⚠️ Also set this in Shopify cart attributes via the Storefront API for reliable webhook capture.
3. Shopify Webhook → Base44 Function
shopifyOrderWebhook is LIVE
Function deployed and ready to receive Shopify order webhooks
Register this URL in Shopify Admin → Settings → Notifications → Webhooks (orders/paid event):
Webhook URL to paste in Shopify Admin
https://api.base44.com/api/apps/[YOUR_APP_ID]/functions/shopifyOrderWebhook
⚠️ Replace [YOUR_APP_ID] with your Base44 app ID (visible in the dashboard URL). Set format to JSON.
The function handles: affiliate_ref from note_attributes → founding member rate (40%) or standard (20%) → CommissionPayout record + User stats + WolfCoin transaction.
4. Base44 Entities Required
affiliate_code (string), affiliate_clicks (number), affiliate_earnings (number)
affiliate_email, order_id, order_total, commission_amount, commission_rate, status, source, order_date
user_email, type, amount, description, reference_id
5. Commission Logic
40%
Founding Rate
20%
Standard Rate
+5%
Inner Circle Bonus
$25 min
Payout Threshold
Founding members (early signups) are flagged with is_founding_member: true on their User record. Check this flag in the webhook to apply the correct rate.
6. Payout Flow
Webhook creates CommissionPayout (status: pending)
Automatic — no manual work needed
Admin reviews in AdminCommissionPayout page
Navigate to /AdminCommissionPayout to see pending payouts
Admin marks as approved → triggers PayPal payout
Use existing PayPal integration (PAYPAL_CLIENT_ID already set)
Status updated to paid, affiliate notified
Send email via Core.SendEmail integration
🤖 Build-Agent Prompt
Paste this into any AI builder or developer handoff:
Copy & hand to your developer
Build a Shopify-to-Base44 affiliate commission bridge:
1. On CareZiaSpace landing pages, capture ?ref= URL param → store in localStorage('affiliate_ref')
2. When user clicks buy on WolfBeansStore, append ref + base44_user_id to Shopify checkout URL
3. In Shopify Admin, register an orders/paid webhook pointing to the Base44 function endpoint for 'shopifyOrderWebhook'
4. The shopifyOrderWebhook Base44 function should:
- Parse the Shopify order payload
- Extract affiliate_ref from note_attributes
- Look up the affiliate user by affiliate_code in Base44 User entity
- Calculate commission (40% for founding members, 20% standard)
- Create a CommissionPayout record with status='pending'
5. Admin approves payouts via /AdminCommissionPayout page using existing PayPal integration
Secrets already set: PAYPAL_CLIENT_ID, PAYPAL_CLIENT_SECRET
Base44 SDK: npm:@base44/sdk@0.8.23