Skip to main content

Shopify App Troubleshooting

Common issues and solutions for the Loyalteez Shopify app integration.

Webhook Issues​

Webhooks Not Being Received​

Symptoms:

  • Orders not triggering rewards
  • Events not tracking
  • Webhook endpoints not called

Solutions:

1. Check Webhook Configuration:

  • Navigate to Shopify Admin → Settings → Notifications → Webhooks
  • Verify webhook URL is correct
  • Check webhook is enabled

2. Check Server Accessibility:

  • Verify server is publicly accessible
  • Test webhook URL: curl -X POST <webhook_url>
  • Check firewall rules allow incoming requests

3. Check Webhook Secret:

  • Verify SHOPIFY_WEBHOOK_SECRET matches Shopify admin
  • Check secret is set correctly in environment
  • Regenerate secret if needed

4. Check Webhook Events:

  • Verify correct events are subscribed
  • Required: orders/create, orders/paid
  • Check webhook event format matches handler

"Getting 401 Unauthorized errors"​

Symptoms:

  • Webhook requests fail with 401
  • "Invalid signature" error
  • Webhook secret mismatch

Solutions:

1. Verify Webhook Secret:

  • Secret must match Shopify Admin → Settings → Notifications → Webhooks
  • Check SHOPIFY_WEBHOOK_SECRET environment variable
  • Verify secret is not empty

2. Check Signature Verification:

  • Verify HMAC signature verification code
  • Check signature calculation matches Shopify format
  • Review webhook handler signature verification

3. Regenerate Webhook Secret:

  • Delete existing webhook in Shopify Admin
  • Create new webhook with new secret
  • Update SHOPIFY_WEBHOOK_SECRET in environment

Webhook Payload Issues​

Symptoms:

  • Webhook received but data missing
  • Order data not parsed correctly
  • Event data incomplete

Solutions:

1. Check Payload Format:

  • Verify payload is valid JSON
  • Check payload structure matches Shopify format
  • Review webhook handler parsing logic

2. Check Required Fields:

  • Verify order has required fields: email, total_price
  • Check customer email is present
  • Verify order total is numeric

3. Enable Debug Logging:

  • Log webhook payload for debugging
  • Review payload structure
  • Check for missing fields

Widget Issues​

Widget Not Displaying​

Symptoms:

  • Widget not showing on storefront
  • Widget code not rendering
  • No widget output

Solutions:

1. Check Widget Installation:

  • Verify widget code is added to theme
  • Check theme template files
  • Verify widget script is included

2. Check JavaScript Errors:

  • Open browser console (F12)
  • Check for JavaScript errors
  • Verify widget script is loaded

3. Check Customer Email:

  • Widget requires customer email
  • Verify customer is logged in
  • Check customer email is available

4. Check Brand ID:

  • Verify Brand ID is configured
  • Check widget initialization
  • Verify Brand ID format is correct

Widget Not Loading Data​

Symptoms:

  • Widget shows "Loading..." forever
  • Data not fetching
  • API errors in console

Solutions:

1. Check API Connection:

  • Verify API URL is accessible
  • Check API response status
  • Review browser console for errors

2. Check Customer Identification:

  • Verify customer email is available
  • Check user identifier format
  • Verify API accepts customer email

3. Check CORS:

  • Verify CORS headers are set
  • Check API allows cross-origin requests
  • Review browser console for CORS errors

4. Check Network Requests:

  • Open browser Network tab
  • Check API requests are being made
  • Review request/response details

Daily Check-in Not Working​

Symptoms:

  • Check-in button doesn't work
  • Streak not updating
  • Error when checking in

Solutions:

1. Check User Login:

  • Customer must be logged in
  • Verify customer session is active
  • Check customer email is available

2. Check Shared Services:

  • Verify shared services URL is correct
  • Check shared services API status
  • Review API response for errors

3. Check API Endpoint:

  • Verify check-in endpoint is accessible
  • Check endpoint requires authentication
  • Review API response

4. Check Error Messages:

  • Review browser console
  • Check API error responses
  • Verify error message details

Perk Redemption Fails​

Symptoms:

  • Perk purchase button doesn't work
  • Transaction fails
  • Error when redeeming

Solutions:

1. Check Customer Balance:

  • Verify customer has sufficient LTZ
  • Check balance is displayed correctly
  • Verify balance is current

2. Check Perk Availability:

  • Verify perk is available
  • Check perk supply limits
  • Verify perk is active

3. Check API Connection:

  • Verify shared services API
  • Check redemption endpoint
  • Review API response

4. Check Transaction:

  • Verify blockchain transaction
  • Check transaction status
  • Review transaction hash

Configuration Issues​

Brand ID Not Working​

Symptoms:

  • Rewards not distributing
  • Events not tracking
  • Brand ID error

Solutions:

1. Verify Brand ID:

  • Brand ID must be wallet address format
  • Format: 0x1234567890abcdef1234567890abcdef12345678
  • Copy from Partner Portal → Settings → Account

2. Check Brand ID Format:

  • Must start with 0x
  • Must be 42 characters total
  • Must be valid Ethereum address

3. Check Partner Portal:

  • Verify Brand ID matches Partner Portal
  • Check account is active
  • Verify automation is enabled

Rewards Not Distributing​

Symptoms:

  • Orders processed but no rewards
  • Events track but no LTZ
  • Wallet balance not increasing

Solutions:

1. Check Automation Status:

  • Verify automation is enabled in Partner Portal
  • Navigate to Partner Portal → Automation
  • Toggle "Enable Automation" to ON

2. Check Event Configuration:

  • Verify event has reward configured
  • Check reward amount is set
  • Verify event is active

3. Check Cooldown Periods:

  • User may be on cooldown
  • Check cooldown settings in Partner Portal
  • Verify event hasn't been rewarded recently

4. Check Rate Limits:

  • User may have hit rate limit
  • Check rate limit settings
  • Wait for cooldown period

Integration Issues​

Orders Not Triggering Rewards​

Symptoms:

  • Orders complete but no events
  • Webhooks not triggering
  • No rewards for purchases

Solutions:

1. Check Webhook Configuration:

  • Verify webhooks are configured in Shopify Admin
  • Check webhook URL is correct
  • Verify webhook events are subscribed

2. Check Webhook Handler:

  • Verify webhook handler is deployed
  • Check handler is accessible
  • Review handler logs

3. Check Order Events:

  • Verify order events are triggering
  • Check order status matches webhook filter
  • Review webhook payload

4. Check API Connection:

  • Verify API URL is accessible
  • Check API response codes
  • Review API logs

Customer Signup Not Rewarding​

Symptoms:

  • New customers not receiving rewards
  • Signup events not tracking
  • Welcome bonus not distributed

Solutions:

1. Check Customer Event:

  • Verify customer creation event is configured
  • Check event name matches Partner Portal
  • Verify event is active

2. Check Webhook Configuration:

  • Verify customer webhooks are configured
  • Check webhook URL is correct
  • Verify webhook events are subscribed

3. Check Customer Data:

  • Verify customer email is present
  • Check customer email format is valid
  • Verify customer is active

4. Check Automation:

  • Verify automation is enabled
  • Check event has reward configured
  • Verify reward amount is set

Widget Customization Issues​

Widget Styling Issues​

Symptoms:

  • Widget not matching theme
  • CSS conflicts
  • Layout broken

Solutions:

1. Check Theme CSS:

  • Review theme CSS for conflicts
  • Use browser inspector to identify conflicts
  • Add custom CSS to override

2. Custom Styling:

  • Add custom CSS to theme
  • Target widget classes specifically
  • Use CSS specificity to override

3. Check Widget CSS:

  • Verify widget CSS is loaded
  • Check for CSS conflicts
  • Review widget class names

Widget Not Responsive​

Symptoms:

  • Widget breaks on mobile
  • Layout issues on small screens
  • Not mobile-friendly

Solutions:

1. Check CSS Media Queries:

  • Verify responsive CSS is included
  • Check media query breakpoints
  • Test on different screen sizes

2. Check Widget Container:

  • Verify container width is responsive
  • Check max-width settings
  • Review container CSS

3. Test on Devices:

  • Test on mobile devices
  • Check tablet layout
  • Verify desktop layout

Performance Issues​

Widget Loading Slowly​

Symptoms:

  • Widget takes long to load
  • API requests slow
  • Poor user experience

Solutions:

1. Check API Performance:

  • Verify API response times
  • Check API server status
  • Review API logs

2. Check Network:

  • Verify network connection
  • Check CDN is enabled
  • Review asset loading

3. Optimize Requests:

  • Reduce API requests
  • Cache API responses
  • Use lazy loading

Getting Help​

If you're still experiencing issues:

  1. Check Documentation:

  2. Review Logs:

    • Webhook handler logs
    • Browser console errors
    • API logs

  3. Contact Support:

Need help? [email protected]

Last updated on