> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datalyr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration Errors

> Troubleshoot Shopify, Stripe, and ad platform integration issues

Integration connection failing or data not syncing? This guide covers common integration errors and solutions.

## Quick Diagnostic

**Check Integration Status:**

1. Go to **Integrations → Overview**
2. Look for each integration's status
3. Check "Last Sync" timestamp

**Status Indicators:**

* **Connected:** Working properly
* **Disconnected:** Not connected or expired
* **Error:** Connection issue or sync failure
* **Syncing:** Currently pulling data

## Common Integration Errors

### "OAuth Connection Expired"

**Platforms:** Meta, Google, TikTok

**Symptoms:**

* Integration shows "Disconnected"
* Conversions not sending to platform
* Error: "Access token expired"

**Why It Happens:**
OAuth tokens expire after 60-90 days for security.

**Fix:**

1. Go to **Integrations → \[Platform]**
2. Click "Reconnect"
3. Authorize DATALYR again in popup
4. Verify "Connected" status

**Prevention:**
Reconnect integrations quarterly or when notified.

### "Invalid Access Token"

**Platforms:** Meta, Google, TikTok

**Symptoms:**

* Integration connects but immediately fails
* Postbacks show "Failed" status
* Error: "Invalid OAuth 2.0 Access Token"

**Causes:**

* Token revoked in ad platform
* User permissions changed
* Account access removed

**Fix:**

**Meta:**

1. Go to [Meta Business Settings](https://business.facebook.com/settings)
2. System Users → Check DATALYR has admin access
3. Reconnect in DATALYR

**Google:**

1. Go to [Google Account Permissions](https://myaccount.google.com/permissions)
2. Remove DATALYR access
3. Reconnect in DATALYR (grants fresh token)

**TikTok:**

1. Go to [TikTok Business Center](https://business.tiktok.com)
2. Settings → Authorized Apps → Remove DATALYR
3. Reconnect in DATALYR

### "Missing Required Permissions"

**Platforms:** Meta, Google, TikTok

**Symptoms:**

* Connection succeeds but features don't work
* Can't send conversions
* Error: "Insufficient permissions"

**Required Permissions:**

**Meta:**

* ads\_management
* business\_management

**Google:**

* Google Ads API access
* Conversion tracking permissions

**TikTok:**

* Event Management
* Ad Account access

**Fix:**

1. Disconnect integration
2. Reconnect using admin account with full permissions
3. Grant all requested permissions during OAuth

### "Account Not Found"

**Platforms:** Meta, Google, TikTok

**Symptoms:**

* Can't select ad account during setup
* Error: "No eligible accounts found"

**Causes:**

* Wrong account used for OAuth
* Ad account not accessible to user
* Business Manager not configured

**Fix:**

**Meta:**
Ensure you're admin of both:

* Meta Business Manager account
* Ad account you want to track

**Google:**

* Use account with Google Ads access
* Verify ad account ID is correct

**TikTok:**

* Use TikTok Business Center admin account
* Verify ad account is active

## Shopify Integration Errors

### "Store Not Accessible"

**Symptoms:**

* Can't connect Shopify store
* Error: "Unable to access store"

**Causes:**

* Wrong store URL
* Store not on paid plan
* App not installed

**Fix:**

**Verify Store URL:**
Use exact Shopify URL: `yourstore.myshopify.com` (not custom domain).

**Check Plan:**
Shopify Basic plan or higher required.

**Install App:**
If using App Store installation:

1. Visit [Shopify App Store](https://apps.shopify.com)
2. Search "DATALYR"
3. Install app
4. Authorize access

### "Webhook Delivery Failed"

**Symptoms:**

* Integration connected
* Orders not syncing
* Error in webhook logs

**Causes:**

* Webhook URL blocked
* Shopify webhook limit reached
* Store firewall blocking requests

**Fix:**

**Check Webhooks:**

1. Shopify Admin → Settings → Notifications
2. Scroll to Webhooks
3. Look for DATALYR webhooks
4. Verify status is "Active"

**Webhook Limit:**
Shopify limits webhooks per store.

**Fix:** Remove unused webhooks, ensure DATALYR webhooks present.

**Recreate Webhooks:**

1. DATALYR: Disconnect Shopify
2. Wait 1 minute
3. Reconnect Shopify (recreates webhooks)

### "Missing Order Data"

**Symptoms:**

* Orders syncing
* Revenue or products missing
* Incomplete data

**Causes:**

* Order status not "paid"
* Custom checkout fields not mapped
* Product metadata missing

**Fix:**

**Order Status:**
Only paid orders sync. Check order is paid in Shopify.

**Product Data:**
For profit tracking, add COGS to product metadata:

1. Shopify → Products → Select product
2. Metafields → Add "cost\_per\_item"
3. Enter cost value

See [Profit Tracking](/features/profit-tracking).

### "CORS Error"

**Symptoms:**

* Shopify Web Pixels installation
* Browser console: "CORS policy error"

**Why It Happens:**
Shopify Web Pixels sandbox restrictions.

**Fix:**
Use server-side tracking (webhooks) instead of Web Pixels for critical data.

Or install tracking script in theme (not Web Pixels).

See [Shopify Manual Installation](/getting-started/installation/platforms/shopify-manual).

## Stripe Integration Errors

### "Invalid API Key"

**Symptoms:**

* Can't connect Stripe
* Error: "API key invalid"

**Causes:**

* Wrong API key type
* Key from test mode
* Key revoked

**Fix:**

**Reconnect via OAuth:**
DATALYR uses Stripe Connect OAuth for authentication.

**Reconnect Stripe:**

1. Go to Settings → Integrations
2. Disconnect the existing Stripe connection
3. Click "Connect" to start a new OAuth flow
4. Authorize DATALYR in Stripe
5. Verify the connection shows "Connected"

See [Stripe Integration](/integrations/stripe).

**Test vs Live:**
Ensure you are connecting your live Stripe account, not a test account.

### "No Events Found"

**Symptoms:**

* Stripe connected
* Zero payments in DATALYR
* Error: "No events to sync"

**Causes:**

* No recent payments
* Wrong event types tracked
* API key permissions too restrictive

**Fix:**

**Check Events:**

1. Stripe Dashboard → Developers → Events
2. Look for `charge.succeeded` events
3. Verify events exist in last 30 days

**Permissions:**
Restricted key must have read access to Events resource.

**Test Integration:**
Create test payment in Stripe, verify appears in DATALYR within 15 minutes.

### "Customer Metadata Missing"

**Symptoms:**

* Payments syncing
* Not attributed to website visitors
* All showing as "Direct"

**Causes:**

* Customer metadata not set
* Anonymous ID not passed to Stripe

**Fix:**

**Include Visitor ID in Metadata:**

```javascript theme={null}
const anonymousId = datalyr.getAnonymousId();

const customer = await stripe.customers.create({
  email: 'user@example.com',
  metadata: {
    datalyr_visitor_id: anonymousId,
    datalyr_user_id: userId  // Optional
  }
});
```

See [Stripe Integration](/integrations/stripe#attribution-linking).

### "MRR Calculation Incorrect"

**Symptoms:**

* Subscriptions syncing
* MRR showing wrong amount

**Causes:**

* Baseline not set
* Mixed intervals (monthly, annual)
* Duplicate subscriptions

**Fix:**

**Reset Baseline:**

1. Integrations → Stripe
2. Click "Reset MRR Baseline"
3. Takes snapshot of current MRR
4. Future changes calculated from baseline

**Verify Intervals:**
Check subscription intervals normalized correctly:

* Annual: Amount / 12
* Quarterly: Amount / 3
* Weekly: Amount \* 4.33

## Ad Platform Integration Errors

### Meta Ads

**"Pixel Already Installed":**

**Issue:**
Both DATALYR CAPI and Meta Pixel on site.

**Impact:**
May cause duplicate conversions in Meta reporting.

**Fix:**
Keep both installed. DATALYR automatically deduplicates via `event_id` parameter.

Or remove Meta Pixel, use DATALYR only for conversion tracking.

**"Dataset Not Found":**

**Error:** "Pixel dataset not accessible"

**Causes:**

* Pixel ID incorrect
* Dataset deleted
* No access to pixel

**Fix:**

1. Meta Events Manager → Data Sources
2. Find your pixel
3. Copy pixel ID
4. Update in DATALYR → Integrations → Meta

**"Upload Limit Exceeded":**

**Error:** "Too many events sent"

**Cause:**
Meta CAPI rate limit (millions of events/day).

**Fix:**
Contact [hello@datalyr.com](mailto:hello@datalyr.com) to optimize event sending.

Temporary: Reduce conversion rule to essential events only.

### Google Ads

**"Conversion Action Not Found":**

**Error:** "Specified conversion action does not exist"

**Causes:**

* Wrong conversion action name
* Conversion action deleted
* Wrong account linked

**Fix:**

1. Google Ads → Tools → Conversions
2. Copy exact conversion action name
3. Update in DATALYR Conversion Rule

**"Enhanced Conversions Not Enabled":**

**Error:** "Enhanced conversions disabled"

**Cause:**
Google Ads account doesn't have Enhanced Conversions enabled.

**Fix:**

1. Google Ads → Tools → Conversions
2. Select conversion action
3. Settings → Enhanced conversions → Turn on

**"Customer Match Not Working":**

**Error:** "Email not matched"

**Causes:**

* Email not SHA-256 hashed
* Email format incorrect
* User not in Google audience

**Fix:**
Ensure email provided in conversion event:

```javascript theme={null}
datalyr.track('purchase', {
  revenue: 99.99,
  email: 'user@example.com'  // DATALYR hashes automatically
});
```

### TikTok Ads

**"Event Code Missing":**

**Error:** "Missing TikTok pixel code"

**Causes:**

* Pixel ID not configured
* Wrong pixel ID
* Pixel not installed

**Fix:**

1. TikTok Ads Manager → Assets → Events
2. Copy pixel code
3. DATALYR → Integrations → TikTok → Enter pixel code

**"Contents Field Required":**

**Error:** "Missing contents array"

**Cause:**
TikTok requires `contents` for e-commerce events.

**Fix:**

```javascript theme={null}
datalyr.track('purchase', {
  revenue: 99.99,
  currency: 'USD',
  contents: [
    {
      content_id: 'prod_123',
      quantity: 1,
      price: 99.99
    }
  ]
});
```

**"Test Event Not Appearing":**

**Issue:**
Test events not showing in TikTok Events Manager.

**Cause:**
Test mode not enabled in DATALYR.

**Fix:**

1. Integrations → Conversion Rules
2. Edit rule → Enable "Test Mode"
3. Send test event
4. Check TikTok Events Manager → Test Events

### Superwall

**Webhook Not Receiving Events**

1. Verify the webhook URL in Superwall Dashboard -> Settings -> Webhooks
2. Check that the DATALYR workspace is connected (Settings -> Integrations)
3. Ensure the Superwall Project ID matches your DATALYR connection
4. Check for sandbox events (only production events are processed)

**Revenue Not Attributed**

1. Verify the user's email is set in Superwall's userAttributes
2. Check that `identify()` was called in the DATALYR mobile SDK before the purchase
3. Confirm the email matches between Superwall and DATALYR

### RevenueCat

**Webhook Not Receiving Events**

1. Verify the webhook URL in RevenueCat Dashboard -> Project Settings -> Webhooks
2. Check the Authorization header matches your DATALYR configuration
3. Ensure sandbox events are filtered (production only)

**Revenue Not Attributed**

1. Verify the user's \$email is set in RevenueCat subscriber attributes
2. Check that `identify()` was called in the DATALYR mobile SDK
3. Confirm aliases include a non-anonymous user ID

## Sync Frequency Issues

**Problem:**
Data taking too long to sync.

**Sync Frequencies:**

* **Shopify:** Real-time (webhooks)
* **Stripe:** Real-time (webhooks)
* **Ad Platforms:** 15 minutes (batch)

**If Delayed:**

**Check Status:**
Integrations → Overview → Check "Last Sync" timestamp.

**If Stale (>1 hour):**

1. Disconnect integration
2. Wait 1 minute
3. Reconnect integration
4. Monitor sync status

**Still Delayed:**
Contact [hello@datalyr.com](mailto:hello@datalyr.com) with integration name and workspace ID.

## Webhook Failures

**Symptoms:**

* Shopify/Stripe connected
* Orders/payments not syncing
* Error logs showing failures

**Common Webhook Errors:**

**"Timeout":**
Webhook took too long to process.

**Fix:** Automatic retry after 5 minutes. If persistent, contact support.

**"401 Unauthorized":**
Webhook authentication failed.

**Fix:**

1. Disconnect integration
2. Reconnect (regenerates webhook secret)

**"422 Unprocessable Entity":**
Webhook payload invalid.

**Fix:** Check Shopify/Stripe order data is complete. Contact support if persists.

**"500 Internal Server Error":**
DATALYR server issue (rare).

**Fix:** Automatic retry. Contact support if persistent.

## Testing Integrations

**Before Going Live:**

**1. Test Connection:**

1. Connect integration
2. Verify "Connected" status
3. Check "Last Sync" updates

**2. Test Data Flow:**

**Shopify:**
Create test order, verify appears in DATALYR within 1 minute.

**Stripe:**
Create test payment, verify appears within 15 minutes.

**Ad Platforms:**
Send test conversion, check Event Stream and platform reporting.

**3. Verify Attribution:**
Create test conversion with known attribution (click ad yourself), verify attributed correctly.

## Rate Limits

**API Rate Limits:**

* Meta: 200 requests/hour
* Google: 2,000 requests/day
* TikTok: 1,000 requests/hour
* Shopify: 2 requests/second
* Stripe: 100 requests/second

**If Rate Limited:**
DATALYR automatically retries with backoff. Contact [hello@datalyr.com](mailto:hello@datalyr.com) if limits consistently exceeded.

## Still Having Issues?

**Debug Checklist:**

1. Integration shows "Connected"?
2. Last sync timestamp recent?
3. Permissions granted during OAuth?
4. Using correct account (admin access)?
5. Webhook endpoints accessible?
6. Test transaction completed?

**Contact Support:**
Email [hello@datalyr.com](mailto:hello@datalyr.com) with:

* Integration name (Shopify, Stripe, Meta, etc.)
* Error message screenshot
* Integration status screenshot
* Example transaction (order ID, timestamp)
* Workspace ID

## Next Steps

<CardGroup cols={2}>
  <Card title="Postback Debugging" icon="bug" href="/troubleshooting/postback-debugging">
    Debug postback failures
  </Card>

  <Card title="Missing Conversions" icon="chart-line" href="/troubleshooting/missing-conversions">
    Fix conversion tracking
  </Card>

  <Card title="Shopify Integration" icon="bag-shopping" href="/integrations/shopify">
    Shopify setup guide
  </Card>

  <Card title="Stripe Integration" icon="stripe" href="/integrations/stripe">
    Stripe setup guide
  </Card>
</CardGroup>