Documentation

What is ShopiPixel?

ShopiPixel is a Shopify app for Server-Side Conversion Tracking. Instead of sending tracking data through your customers' browsers, ShopiPixel transmits orders and customer actions directly from your server to advertising platforms like Meta, Google Analytics, TikTok and more.

Why Server-Side Tracking?

Traditional browser tracking is becoming increasingly unreliable: ad blockers prevent data transmission, iOS restrictions shorten cookie lifespans, and browsers block third-party cookies. The result: your ad campaigns appear to perform worse than they actually do.

With server-side tracking, ShopiPixel sends data directly and securely to the platforms — independent of the browser. This means: more recognized conversions, more accurate data and a better return on ad spend (ROAS).

Dual-Track: Maximum Data Quality

ShopiPixel combines two data sources for the highest accuracy:

• Browser Tracking (Web Pixel): Captures click IDs from ad URLs and browser data like session identifiers.
• Server Webhooks: Receives complete order data directly from Shopify — reliable and independent of the browser.

Both sources are automatically merged so that each event contains the best possible data.

Getting Started & Setup

Installation only takes a few minutes. You'll be up and running in three steps:

1. Install the app
   Install ShopiPixel from the Shopify App Store. The web pixel is activated automatically.
2. Connect a platform
   Go to settings and enter the credentials of your advertising platform (e.g. Meta Pixel ID and Access Token). A detailed guide for each of the 10 platforms can be found at Platform Setup.
3. Platform-side configuration
   In addition to credentials, the platform itself must be configured. For Google Ads, for example, Enhanced Conversions with the method "Google Ads API" must be enabled for API events to be processed. Details per platform can be found in the Setup Guide.
4. Check events
   Perform a test action in your store and check in the dashboard whether events are sent successfully. Also verify in the respective advertising platform that events arrive and are processed.

Detailed Guides

Dashboard

The dashboard gives you a real-time overview of your tracking. At a glance, you can see how your events are performing.

KPI Cards

Revenue Chart

The chart shows your revenue over time. You can choose different time periods (today, 7 days, 30 days, month). Available time periods depend on your plan.

Conversion Funnel

The funnel visualizes your customers' journey through the purchase process:

• Page View → Product View → Cart → Checkout → Purchase

At each stage, you can see how many visitors drop off. This helps you identify weak points in your store and optimize accordingly.

Platform Comparison

Compare events and success rate per connected platform. This lets you immediately spot if a platform has issues or performs particularly well.

Live Events

The event feed shows you the latest events in real time — with event type, platform and status. Failed events are highlighted in color.

Top Products

An overview of your best-selling products, sorted by revenue. Shows product name, number of sales and total revenue.

Tracking & Consent

Tracking Modes

In settings, you can choose how ShopiPixel collects data:

Consent Management (GDPR)

ShopiPixel respects your customers' consent. Tracking events are only sent when valid consent is given.

Shopify Privacy Banner

Shopify's built-in privacy banner is automatically detected. No additional configuration needed.

Third-Party Consent Management

ShopiPixel supports all major consent management platforms:

• Cookiebot
• OneTrust
• Pandectes
• Consentmo
• Custom CMP solution

Consent signals are automatically detected and evaluated.

Google Consent Mode v2

ShopiPixel supports Google Consent Mode v2 with the signals "Ad User Data" and "Ad Personalization". These are automatically transmitted to Google Analytics 4 and Google Ads.

Consent Logging

Each consent is logged with timestamp, document version and legal basis (Art. 7 GDPR). These records are available in the app under Settings.

Enhanced Conversions

ShopiPixel sends pseudonymized customer data (hashed email, phone number) to the platforms. This improves the matching of events to real users and significantly increases the event match quality on Meta, Google and other platforms.

Events

ShopiPixel automatically captures all relevant e-commerce events in your Shopify store and sends them to your connected platforms.

Supported Events

Event Sources

• Browser (Web Pixel): Captures events directly in your customer's store. Contains click IDs and cookie data for better attribution.
• Server (Shopify Webhooks): Receives complete order data directly from Shopify — reliable and independent of the browser.
• Both sources are automatically merged for maximum data quality.

Automatic Deduplication

ShopiPixel automatically detects and removes duplicate events. When a purchase is reported by both the web pixel and webhook, only one event is sent to the platform — with the combined data from both sources.

Dual-Track: Cross-Source Deduplication

In dual-track mode (web pixel + webhooks active), Purchase and InitiateCheckout events are deduplicated across channels. Once the web pixel has successfully sent an event to all platforms, the repeated send is automatically skipped. This reliably prevents duplicate conversions in GA4, Meta, TikTok and all other platforms — without any configuration required.

Event Browser

In the app under "Events" you can view all events:

• Filter by platform and status
• CSV export (from STARTER plan)
• Event details: timestamp, status, platform, error message

Automatic Retry

Failed events are automatically retried. This way no data is lost, even if a platform is temporarily unavailable.

Event Configuration

Event configuration lets you control which events are sent to which platforms. By default, all events are sent to all configured platforms (full-funnel tracking).

The opt-out pattern means: Only when you explicitly disable an event for a specific platform will it no longer be sent there. This gives you full control over your event routing.

Custom Events

Custom Events let you define your own event types that go beyond standard e-commerce events. Each custom event can have a unique name and individual per-platform mapping.

A maximum of 20 custom events can be created per store. Event names must be alphanumeric (including underscore, max 64 characters). Delivery uses the existing platform clients. Note: Snapchat allows a maximum of 5 custom events.

Trigger custom events via API

Once a custom event is defined in the app, you can trigger it via the Public REST API at POST /api/v1/events — using the same event name you assigned in the wizard.

See the "Public REST API" section for details. Public REST API

Offline Deals

Offline deals are sales that happen outside the Shopify checkout — typically over the phone, via email, or at in-person meetings. With ShopiPixel you can capture these deals in the dashboard and send them as offline conversions to your ad platforms, so that campaign optimisation also takes B2B revenue into account.

Capturing deals

In the ShopiPixel dashboard under Offline Deals you can create deals manually or import them in batches via CSV upload. For each deal you record the amount, currency, close date, optionally a click ID (gclid, fbclid, msclkid, ttclid, epik, scid, liFatId, wbraid or gbraid), and the customer's email and phone number for pseudonymised attribution.

Click-ID matching

If a prospect clicks on an ad before the deal closes, the ad platform appends a unique click ID to the landing page URL. ShopiPixel stores the click ID at first contact (lead capture) for up to 90 days. When you create the offline deal the matching click ID is attached automatically, so the platforms can attribute the offline revenue to the original campaign.

Enhanced Matching — cold deals without a click ID

When there is no prior ad click (for example cold phone calls, referrals, trade-show leads), we additionally submit the customer's hashed contact data to the ad platform. The platform matches the hash against its own user database and assigns the deal to the matching user profile. Plain text never leaves our server — only the irreversible hash value is transmitted. The legal basis is the legitimate interest under Art. 6(1)(f) GDPR; details are described in the privacy policy and the data processing agreement.

Per-platform lookback window

Every ad platform has its own attribution window. Deals closed later than the platform limit after the original click are dropped on the platform side — ShopiPixel filters those deals before dispatch:

Event Triggers

With event triggers you connect your own data points (e.g. B2B demo requests, newsletter sign-ups, custom workflow steps) with platform-specific event codes. Setup runs in a no-code wizard directly in the dashboard — no code changes in your storefront required.

Supported trigger types

Event triggers can fire from several sources:

• HMAC token API — Send POST requests to /api/events/trigger with a signed token — ideal for external systems like CRM, ticketing tools, or event platforms.
• Shopify webhook mapping — Map existing Shopify webhook topics like orders/create or checkouts/create to your custom events. Every webhook call triggers the linked event automatically.
• Shopify Flow Action — Use ShopiPixel as a custom action directly inside the Shopify Flow editor (Shopify Plus only). Details in the Shopify Flow Action section.

Five-step wizard

Open the wizard in the dashboard under Settings → Event Triggers and follow five steps:

1. 1. Basics — name and description
   Set the event name (alphanumeric, max. 64 characters) and description.
2. 2. Platform event picker
   For every active ad platform, choose the matching official event — for example Lead on Meta, a conversion action on Google Ads, a conversion goal on Microsoft Ads. The list is loaded live from the platform APIs.
3. 3. Smart default matching
   ShopiPixel suggests suitable platform events automatically based on the event name (fuzzy match with a German-English synonym list). You can accept the suggestions with one click or override them.
4. 4. Trigger configuration
   Choose the trigger type (API token, webhook mapping, or flow action) and, for API triggers, generate the HMAC token for your external system.
5. 5. Review and save
   Review the per-platform payload preview and save. The event is active immediately and gets dispatched to all linked platforms on every trigger.

Platform event picker

For each of the nine supported platforms (Meta with 17 standard events, Google Ads GAQL conversion actions incl. MCC support, Microsoft Ads conversion goals, TikTok 14 events, Pinterest 14 events, Snapchat 16 events, LinkedIn lead forms + 7 standard events, Klaviyo metrics) you can pick the matching official event from a dropdown. Event catalogs are cached for an hour so the wizard UI stays responsive.

Smart defaults and preview

A built-in fuzzy-match algorithm (Levenshtein-based) compares your event name against a German-English synonym list and automatically suggests the right platform mapping. For each platform the wizard shows a preview of the generated payload so you can see how the event will look on Meta, Google Ads & co. before saving.

Webhook Mapping

Webhook mapping links Shopify webhook topics to your custom events per platform. As soon as Shopify fires the webhook, ShopiPixel dispatches the linked event automatically to all configured ad platforms — no extra code in the storefront required.

How does the mapping work?

In the dashboard under Settings → Event Triggers → Webhooks you define per Shopify topic which custom event should fire. Multiple mappings per topic are supported — for example orders/create can trigger both a 'B2B deal closed' event and a 'newsletter opt-in' event. The mappings are cached in Redis for five minutes so changes take effect quickly while the webhook path stays fast.

Supported Shopify topics

Nine Shopify webhook topics are currently available as triggers:

• orders/create — A new order was created
• orders/updated — An existing order was updated
• orders/cancelled — Order was cancelled
• orders/fulfilled — Order was fully shipped
• checkouts/create — Checkout was started
• carts/create — Cart was created
• customers/create — A new customer account was created

Limits

A maximum of 20 webhook mappings are active per store. Multiple mappings can share a topic — each mapping is dispatched independently. Inactive mappings do not count against the limit.

Shopify Flow Action

ShopiPixel appears as a custom action directly inside the Shopify Flow editor. With it you can send events from any Shopify Flow workflow to ShopiPixel — without HMAC tokens or API configuration. The complete event pipeline including platform router, consent checks, and rate limiting kicks in automatically.

Requirements

Shopify Flow is only available on the Shopify Plus plan. In addition you need the ShopiPixel Enterprise plan. Both requirements are checked automatically when the action runs — if one is missing the Flow editor shows a matching note.

Setup inside the Flow editor

1. 1. Create a flow
   Open the Flow editor in your Shopify admin and create a new flow — or edit an existing one. Pick a trigger (e.g. 'Order created', 'Customer tagged', 'Product variant created').
2. 2. Add the ShopiPixel action
   Under 'Actions' add the ShopiPixel custom action. It appears in the action list as 'Send ShopiPixel Event'.
3. 3. Pick a custom event
   In the embedded config page choose the custom event from a dropdown that should fire on every flow run. The list shows all custom events configured in your store.

Replay protection and idempotency

To make sure Shopify Flow retries do not produce duplicate events, ShopiPixel deduplicates by action_run_id for 24 hours. An identical resend within this window is dropped and answered with HTTP 204 — the flow continues, but the event reaches the platforms only once.

Attribution

ShopiPixel detects which advertising platform brought a customer to your store. This attribution is based on click IDs that are automatically captured from ad URLs.

Click-ID Tracking

When a customer clicks on an ad, the platform appends a unique identifier to the URL. ShopiPixel captures these automatically:

Automatic Bridging

Click IDs from the browser are automatically merged with server order data. No manual configuration needed — ShopiPixel handles the attribution completely.

Attribution Models

Depending on your plan, various attribution models are available:

• Last Click — The last click before purchase is credited
• First Click — The first touchpoint is credited
• Linear — All touchpoints are weighted equally
• Time Decay — More recent touchpoints are weighted more heavily
• Position Based — First and last touchpoint are emphasized
• Data Driven — Algorithmic weighting based on your data

Customer Journey

The customer journey shows the complete path of your customers from first contact to purchase. This helps you identify which touchpoints lead to conversions and where optimization potential lies.

Funnel Flow

The funnel flow visualizes the stages: Page view → Product view → Cart → Checkout → Purchase. At each stage, you can see the drop-off rate and identify weak points in your store. You can find the funnel in the dashboard under the Conversion Funnel widget.

Analyzing Individual Journeys

In the Attribution section, you can open individual orders and trace the complete customer path: Which platform was the first contact from? Which click ID was used? How long did the purchase process take? This information helps you optimize your campaigns in a targeted way.

Multi-Touchpoint Analysis

With multiple touchpoints (e.g. first Facebook click, then Google search, then direct visit), ShopiPixel shows all involved platforms chronologically — with timestamp and click ID. This way you understand the complete customer journey across multiple channels.

Ad Spend & ROAS

ShopiPixel can import ad spend from your connected platforms so you can see Return on Ad Spend (ROAS) directly in the dashboard — without switching between different tools.

Connecting Ad Accounts

The connection uses the same credentials you have already set up for tracking. For Meta, the Ad Account ID is additionally required, for Google Ads the Customer ID. Ad spend is retrieved via the respective platform API.

Import Schedule

Ad spend is updated at least once daily. Depending on the platform, data may arrive with a delay of up to 24 hours, as platforms provide their spend data with a time lag.

ROAS Calculation

ROAS = Revenue / Ad Spend. A ROAS of 3.0 means: for every dollar spent, 3 dollars in revenue come back. In the Attribution dashboard you can see ROAS per platform and time period. Available from the Growth plan.

Alerts

Alerts automatically notify you when something important happens — so you don't have to keep watching the dashboard constantly.

Rule Types

You can define various alert rules:

• Volume alerts — e.g. sudden drop in events by more than 50%
• Error alerts — e.g. platform unreachable, credential expired
• Billing alerts — e.g. order limit reached at 80%
• Performance alerts — e.g. Event Match Quality below 6.0

Notification Channels

Alerts can be delivered as in-app banners, via email or as webhooks. System-critical alerts (e.g. pixel outage, platform errors) are active by default and cannot be disabled.

Consent Dashboard

The Consent Dashboard shows you the consent rates of your store visitors and their impact on your tracking data quality. Available from the Growth plan.

Consent Rates

See at a glance how many of your visitors accept tracking — broken down by platform and time period. This way you can tell whether a new cookie banner design has improved the opt-in rate.

Privacy-Friendly Reporting

All data in the Consent Dashboard is displayed without personal information. You see aggregated rates and trends, not individual user profiles.

Event Latency Monitoring

Monitor the latency of your tracking events in real-time — from capture to successful delivery to the advertising platform. Available from the Growth plan.

Latency Metrics

For each platform, you see the average event latency with trend indicators. This way you immediately notice when a platform responds slower than usual or delivery issues occur.

Proactive Warnings

You'll be automatically notified about unusually high latency or repeatedly failed deliveries. This lets you intervene before your data quality is affected.

Token Management

Most platform tokens are permanently valid. Exceptions are Pinterest (30 days) and LinkedIn (60 days). ShopiPixel warns you in time via email.

Token Lifetimes

Meta, Google Analytics 4, TikTok, Google Ads, Snapchat and Klaviyo use permanently valid tokens. Microsoft Ads uses OAuth refresh tokens that remain valid indefinitely as long as the authorization is not revoked in ads.microsoft.com. Pinterest access tokens expire after 30 days, LinkedIn access tokens after 60 days. For these platforms, you need to renew the token regularly.

Automatic Warnings

ShopiPixel monitors the validity of your tokens and sends you a timely email warning before a token expires. This lets you renew the token before tracking is interrupted. Warnings are included in all plans.

Audience Sync

With Audience Sync, you can send customer segments to advertising platforms to create Custom Audiences, Customer Match lists and Customer Lists. Currently Meta, Google Ads, TikTok and Pinterest are supported.

Meta Custom Audiences

Send pseudonymized customer data (hashed email, phone number) to Meta to create Custom Audiences for Facebook and Instagram. Data is transmitted SHA256-hashed — Meta never sees the plaintext data. Custom Audiences enable Lookalike Audiences and more targeted retargeting.

Google Ads Customer Match

Create Customer Match lists in Google Ads with hashed customer data. Google uses these for similar audiences and better bid optimization. Enhanced Conversions must be enabled.

TikTok Custom Audiences

Transfer hashed customer data to TikTok to create Custom Audiences for TikTok Ads. TikTok uses these segments for Lookalike Audiences and more precise retargeting on the platform.

Pinterest Customer Lists

Create Customer Lists on Pinterest with hashed customer data. Pinterest uses these for Actalike Audiences and more targeted campaign delivery on Pinterest.

Hashing & Privacy

All personal data is SHA256-hashed before transmission (one-way hash). Platforms only receive hashed values and cannot reconstruct the original data. Email addresses are normalized before hashing (lowercase, whitespace removed). Phone numbers are converted to E.164 format.

Custom Reports

Create individual reports that show exactly the data relevant to your business.

Available Metrics

Choose from metrics like revenue, conversions, sent events, success rate, average order value (AOV), ROAS, Event Match Quality (EMQ) and more. Up to 10 metrics can be combined in one report.

Dimensions & Filters

Group your data by time period, platform, event type, product or country. Additionally, you can set filters to narrow the report to specific platforms, event types or time periods.

Schedule & CSV Export

Set up automatic delivery — daily, weekly or monthly via email as a CSV attachment. Alternatively, you can export reports manually as CSV or XLSX at any time (from Starter plan).

Cohort Analysis & LTV

Cohort analysis shows how customer groups behave over time. This helps you identify patterns in customer retention and find the most valuable acquisition channels.

Reading the Retention Heatmap

The heatmap shows cohorts (groups of first-time buyers from a specific period) vertically and following months horizontally. The color shows what percentage of the cohort purchased again in the respective month. Darker colors = higher retention. This gives you an at-a-glance view of whether your customer retention remains stable or declines over time.

Understanding Lifetime Value (LTV)

The LTV curve shows cumulative revenue per cohort over time. Compare different cohorts to see which acquisition channels or campaigns bring the most valuable customers long-term. A steep rise in the LTV curve in the first 90 days indicates high repurchase intent.

Data Warehouse Export

Export your tracking data for external analysis to your data warehouse or BI tool.

Destinations

ShopiPixel supports export via Custom Webhook (real-time stream to any endpoint like BigQuery, Snowflake or Redshift), manual CSV/XLSX download and scheduled automatic export via email.

Formats

CSV and XLSX formats are available. The XLSX export additionally includes a summary row, AutoFilter and frozen header row for easier analysis in Excel or Google Sheets.

PII Stripping

During export, personal data (PII) is removed or pseudonymized by default. Email addresses and phone numbers are exported as SHA256 hashes. IP addresses are not exported. This allows you to safely transfer data to external systems.

Creative Analytics

Creative Analytics shows you which ads perform best at the creative level — broken down by image, video or copy.

Available Metrics

For each creative, you see spend, revenue, ROAS, conversions and conversion rate. The data is based on real server-side conversions and is therefore more reliable than pure platform estimates.

Detecting Creative Fatigue

ShopiPixel shows you trend curves per creative. When a creative loses performance over time (declining CTR, rising CPA), you can detect this early and test new variations in time.

Marketing Mix Modelling

Marketing Mix Modelling (MMM) statistically analyzes how different marketing channels interact and contribute to total revenue.

How does MMM work?

MMM uses historical data (ad spend, revenue, seasonality, external factors) to calculate the marginal contribution of each channel. Unlike click attribution, MMM also considers indirect effects like brand awareness and cross-channel interactions.

Budget Simulations

Simulate different budget allocations and see how changes are likely to affect your revenue. Make data-driven budget decisions instead of relying on gut feeling.

Multi-Store Management with Consent Flow

The agency dashboard manages up to 3 linked stores — after active, two-step consent from each shop owner. You act in an impersonation context, only within the delegated permissions.

Two-Step Opt-In Flow

1. As an Enterprise owner, you invite a store and choose the link type: 'Agency-managed' (AGENCY_MANAGED) for service providers or 'Self-owned organization' (SELF_OWNED) for multi-shop operators. 2. The shop owner opens the in-app dialog, sees all shared data categories and individually selects from 14 permissions. The link is only established after active confirmation. The legal basis is the shop owner's consent under Art. 6(1)(a) GDPR; the consent is recorded pursuant to Art. 7(1) GDPR and can be withdrawn at any time under Art. 7(3) GDPR.

14 Granular Capabilities

The shop owner delegates individual tasks: read stats (view_analytics — mandatory), platform configuration (manage_platforms, manage_event_config), tracking settings (manage_tracking_settings), integrations (manage_gtm, manage_headless, manage_ad_accounts), features (manage_audiences, manage_alerts, manage_reports, manage_domain) and data access (download_data, upload_data, access_debug). Events of linked stores count toward the owner quota (100K). The owner's plan is used (ACCEPTED with usesOwnerBilling).

Data Isolation & Audit Log

Each store keeps its own encryption keys, credentials and events. The agency owner sees data only within the delegated permissions. Every action is recorded in the target shop's audit log — fully traceable. The shop owner can end the link at any time (Art. 7(3) GDPR); upon withdrawal, a store paid exclusively through the agency automatically falls back to the FREE plan.

Custom Domain Tracking

Custom Domain Tracking improves data quality by sending events via your own subdomain.

Why Custom Domain?

Browsers like Safari (ITP) and Firefox (ETP) restrict cookies from third-party domains. When you send events via your own subdomain (e.g. track.your-store.com), cookies are treated as first-party. This extends cookie lifetime and improves conversion-to-user attribution.

Setup

Create a CNAME record in your DNS pointing to the ShopiPixel infrastructure. SSL certificates are managed automatically. The transition is possible without data loss.

Headless Commerce SDK

The Headless SDK enables server-to-server event tracking for stores with headless architecture.

When do you need the SDK?

If your storefront is not based on Shopify's standard theme but uses a headless architecture (Hydrogen, Next.js, Gatsby, custom React/Vue), the Shopify Web Pixel does not run in the browser. The SDK handles event delivery directly from the server.

The SDK is built for browser-based tracking from your own storefront. If you want to send events from your server, the Public REST API is the better path — see the "Public REST API" section below.

Requirements

• Scale plan or higher (the SDK is included in the Enterprise plan as well)
• An API key, generated in the app under /app/settings/headless
• Write permission for the linked store — the key only lands in cleartext in the browser once; subsequent calls only carry the hash stored in the database

Step 1: Generate an API key

1. In the ShopiPixel dashboard open /app/settings/headless
2. Click "Generate API key" and assign a meaningful label (e.g. "Hydrogen Production")
3. Copy the displayed key immediately — it is shown in cleartext only once

Step 2: Embed the snippet

Load the SDK asynchronously and initialise it with your API key. The SDK queues events until it is initialised — early calls are not lost.

<script src="https://app.shopipixel.de/api/sdk/js" defer></script>
<script>
  window.ShopiPixel = window.ShopiPixel || {};
  ShopiPixel.queue = ShopiPixel.queue || [];
  ShopiPixel.track = function(e, d) { ShopiPixel.queue.push([e, d]); };
  document.addEventListener('DOMContentLoaded', function() {
    ShopiPixel.init('sp_xxxxxxxxxxxx');
  });
</script>

Step 3: Send events

Use the helper methods for the standard events or the generic track() function for custom event names.

• ShopiPixel.trackPageView()
• ShopiPixel.trackViewContent({ ... })
• ShopiPixel.trackAddToCart({ ... })
• ShopiPixel.trackInitiateCheckout({ ... })
• ShopiPixel.trackPurchase({ ... })
• ShopiPixel.trackSearch({ ... })
• For ViewCategory, CompleteRegistration or custom events: ShopiPixel.track('ViewCategory', { categoryId: 'shoes' })

Public REST API

The Public REST API is ShopiPixel's official server-to-server interface. It lets you send events directly from your own systems, retrieve past events, and read aggregated statistics — without going through browsers or webhooks.

Who is the API for?

The API targets Enterprise customers building server integrations with their own backends, ERP or CRM systems, mirroring conversion data into data warehouses, or generating reports programmatically.

Step 1: Generate an API key

1. In the ShopiPixel dashboard, open /app/settings/api
2. Select the required permissions (events:read, events:write, stats:read — all three are pre-selected by default)
3. Optional: set an expiration date for keys with a limited lifetime
4. Click "Generate key" and copy the displayed key immediately — it is shown in cleartext only once

Step 2: Authentication

Send the API key with every request as a Bearer token in the Authorization header.

Authorization: Bearer sp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Available endpoints

GET /api/v1/events — read events

Returns your events with cursor-based pagination. Cleartext PII (email, phone, first/last name) and click IDs are intentionally not returned — only event metadata and the customData object you originally sent with the POST.

Query parameters

curl -X GET "https://app.shopipixel.de/api/v1/events?limit=50&eventName=Purchase" \
  -H "Authorization: Bearer sp_xxxxxxxxxxxx"

const response = await fetch(
  "https://app.shopipixel.de/api/v1/events?limit=50&eventName=Purchase",
  {
    method: "GET",
    headers: {
      "Authorization": "Bearer sp_xxxxxxxxxxxx",
    },
  },
);

if (!response.ok) {
  throw new Error(`API error: ${response.status} ${response.statusText}`);
}

const { data, pagination } = await response.json();
console.log(`${data.length} Events geladen, hasMore=${pagination.hasMore}`);

import requests

response = requests.get(
    "https://app.shopipixel.de/api/v1/events",
    params={"limit": 50, "eventName": "Purchase"},
    headers={"Authorization": "Bearer sp_xxxxxxxxxxxx"},
)
response.raise_for_status()

payload = response.json()
print(f"{len(payload['data'])} Events geladen, hasMore={payload['pagination']['hasMore']}")

<?php
$ch = curl_init("https://app.shopipixel.de/api/v1/events?limit=50&eventName=Purchase");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer sp_xxxxxxxxxxxx",
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode !== 200) {
    throw new Exception("API error: HTTP $httpCode");
}

$payload = json_decode($response, true);
echo count($payload["data"]) . " Events geladen, hasMore=" . var_export($payload["pagination"]["hasMore"], true);

Response example

{
  "data": [
    {
      "eventId": "purchase_1730000000_abc",
      "eventName": "Purchase",
      "timestamp": "2026-05-08T10:30:00.000Z",
      "source": "API",
      "orderId": "ORDER-123",
      "isRecurring": false,
      "isTest": false,
      "platforms": { "meta": true, "ga4": true },
      "customData": {
        "value": 49.99,
        "currency": "EUR",
        "orderId": "ORDER-123"
      }
    }
  ],
  "pagination": { "nextCursor": "cm123abc", "hasMore": true }
}

Note: Cleartext PII (email, phone, first/last name) and click IDs (fbp, fbc, gclid, …) are not returned — data minimisation per Article 5(1)(c) GDPR. The customData object is returned unchanged (1:1 as sent in the POST) — therefore do not send end-customer PII in customData (e.g. no email, no real name). Business fields like value, currency, orderId, contentIds and numItems are the correct fields.

POST /api/v1/events — create events

Send a single event or up to 100 events in a bulk request. For bulk requests, successful and failed events are reported individually in the response (partial success).

Single event

curl -X POST https://app.shopipixel.de/api/v1/events \
  -H "Authorization: Bearer sp_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "eventName": "Purchase",
    "eventId": "purchase_1730000000_abc",
    "eventTime": 1730000000,
    "userData": {
      "email": "kunde@example.com",
      "phone": "+493099999999"
    },
    "customData": {
      "currency": "EUR",
      "value": 49.99,
      "orderId": "ORDER-123",
      "contents": [
        { "id": "prod-1", "quantity": 1, "itemPrice": 49.99 }
      ]
    }
  }'

const event = {
  eventName: "Purchase",
  eventId: `purchase_${Date.now()}_${crypto.randomUUID().slice(0, 8)}`,
  eventTime: Math.floor(Date.now() / 1000),
  userData: {
    email: "kunde@example.com",
    phone: "+493099999999",
  },
  customData: {
    currency: "EUR",
    value: 49.99,
    orderId: "ORDER-123",
    contents: [{ id: "prod-1", quantity: 1, itemPrice: 49.99 }],
  },
};

const response = await fetch("https://app.shopipixel.de/api/v1/events", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sp_xxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify(event),
});

const result = await response.json();
console.log(`Event ${result.eventId} verarbeitet (duplicate=${result.duplicate})`);

import requests
import time
import uuid

event = {
    "eventName": "Purchase",
    "eventId": f"purchase_{int(time.time())}_{uuid.uuid4().hex[:8]}",
    "eventTime": int(time.time()),
    "userData": {
        "email": "kunde@example.com",
        "phone": "+493099999999",
    },
    "customData": {
        "currency": "EUR",
        "value": 49.99,
        "orderId": "ORDER-123",
        "contents": [{"id": "prod-1", "quantity": 1, "itemPrice": 49.99}],
    },
}

response = requests.post(
    "https://app.shopipixel.de/api/v1/events",
    json=event,
    headers={
        "Authorization": "Bearer sp_xxxxxxxxxxxx",
        "Content-Type": "application/json",
    },
)
response.raise_for_status()

result = response.json()
print(f"Event {result['eventId']} verarbeitet (duplicate={result['duplicate']})")

<?php
$event = [
    "eventName" => "Purchase",
    "eventId" => "purchase_" . time() . "_" . bin2hex(random_bytes(4)),
    "eventTime" => time(),
    "userData" => [
        "email" => "kunde@example.com",
        "phone" => "+493099999999",
    ],
    "customData" => [
        "currency" => "EUR",
        "value" => 49.99,
        "orderId" => "ORDER-123",
        "contents" => [
            ["id" => "prod-1", "quantity" => 1, "itemPrice" => 49.99],
        ],
    ],
];

$ch = curl_init("https://app.shopipixel.de/api/v1/events");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($event));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer sp_xxxxxxxxxxxx",
    "Content-Type: application/json",
]);

$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response, true);

echo "Event {$result["eventId"]} verarbeitet (duplicate=" . var_export($result["duplicate"], true) . ")";

Bulk insert (max 100 events)

Send an array of events. ~50 events per request is optimal — larger batches work, but per-request latency grows linearly.

curl -X POST https://app.shopipixel.de/api/v1/events \
  -H "Authorization: Bearer sp_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '[
    { "eventName": "PageView",         "eventId": "pv_001",  "eventTime": 1730000000 },
    { "eventName": "ViewContent",      "eventId": "vc_001",  "eventTime": 1730000010, "customData": { "contentIds": ["prod-1"] } },
    { "eventName": "AddToCart",        "eventId": "atc_001", "eventTime": 1730000020, "customData": { "value": 49.99, "currency": "EUR", "contentIds": ["prod-1"] } },
    { "eventName": "InitiateCheckout", "eventId": "ic_001",  "eventTime": 1730000030, "customData": { "value": 49.99, "currency": "EUR" } },
    { "eventName": "Purchase",         "eventId": "p_001",   "eventTime": 1730000040, "customData": { "value": 49.99, "currency": "EUR", "orderId": "ORDER-123" } }
  ]'

const events = [
  { eventName: "PageView",         eventId: "pv_001",  eventTime: 1730000000 },
  { eventName: "ViewContent",      eventId: "vc_001",  eventTime: 1730000010, customData: { contentIds: ["prod-1"] } },
  { eventName: "AddToCart",        eventId: "atc_001", eventTime: 1730000020, customData: { value: 49.99, currency: "EUR", contentIds: ["prod-1"] } },
  { eventName: "InitiateCheckout", eventId: "ic_001",  eventTime: 1730000030, customData: { value: 49.99, currency: "EUR" } },
  { eventName: "Purchase",         eventId: "p_001",   eventTime: 1730000040, customData: { value: 49.99, currency: "EUR", orderId: "ORDER-123" } },
];

const response = await fetch("https://app.shopipixel.de/api/v1/events", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sp_xxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify(events),
});

const { successCount, failedCount, results } = await response.json();
console.log(`${successCount}/${events.length} Events erfolgreich, ${failedCount} fehlgeschlagen`);

// Partial-Success-Handling
for (const result of results) {
  if (!result.success) {
    console.warn(`Event ${result.eventId} failed: ${result.error}`);
  }
}

import requests

events = [
    {"eventName": "PageView",         "eventId": "pv_001",  "eventTime": 1730000000},
    {"eventName": "ViewContent",      "eventId": "vc_001",  "eventTime": 1730000010, "customData": {"contentIds": ["prod-1"]}},
    {"eventName": "AddToCart",        "eventId": "atc_001", "eventTime": 1730000020, "customData": {"value": 49.99, "currency": "EUR", "contentIds": ["prod-1"]}},
    {"eventName": "InitiateCheckout", "eventId": "ic_001",  "eventTime": 1730000030, "customData": {"value": 49.99, "currency": "EUR"}},
    {"eventName": "Purchase",         "eventId": "p_001",   "eventTime": 1730000040, "customData": {"value": 49.99, "currency": "EUR", "orderId": "ORDER-123"}},
]

response = requests.post(
    "https://app.shopipixel.de/api/v1/events",
    json=events,
    headers={
        "Authorization": "Bearer sp_xxxxxxxxxxxx",
        "Content-Type": "application/json",
    },
)
response.raise_for_status()
payload = response.json()

print(f"{payload['successCount']}/{len(events)} Events erfolgreich, {payload['failedCount']} fehlgeschlagen")

for result in payload["results"]:
    if not result["success"]:
        print(f"WARN: Event {result['eventId']} failed: {result['error']}")

<?php
$events = [
    ["eventName" => "PageView",         "eventId" => "pv_001",  "eventTime" => 1730000000],
    ["eventName" => "ViewContent",      "eventId" => "vc_001",  "eventTime" => 1730000010, "customData" => ["contentIds" => ["prod-1"]]],
    ["eventName" => "AddToCart",        "eventId" => "atc_001", "eventTime" => 1730000020, "customData" => ["value" => 49.99, "currency" => "EUR", "contentIds" => ["prod-1"]]],
    ["eventName" => "InitiateCheckout", "eventId" => "ic_001",  "eventTime" => 1730000030, "customData" => ["value" => 49.99, "currency" => "EUR"]],
    ["eventName" => "Purchase",         "eventId" => "p_001",   "eventTime" => 1730000040, "customData" => ["value" => 49.99, "currency" => "EUR", "orderId" => "ORDER-123"]],
];

$ch = curl_init("https://app.shopipixel.de/api/v1/events");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($events));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer sp_xxxxxxxxxxxx",
    "Content-Type: application/json",
]);

$response = curl_exec($ch);
curl_close($ch);
$payload = json_decode($response, true);

echo "{$payload["successCount"]}/" . count($events) . " Events erfolgreich, {$payload["failedCount"]} fehlgeschlagen\n";

foreach ($payload["results"] as $result) {
    if (!$result["success"]) {
        echo "WARN: Event {$result["eventId"]} failed: {$result["error"]}\n";
    }
}

For bulk requests, every event is processed individually. Successes and failures are reported in the results array.

{
  "successCount": 4,
  "failedCount": 1,
  "results": [
    { "eventId": "pv_001",  "success": true,  "duplicate": false, "platforms": { "queued": ["meta", "ga4"], "skipped": [] } },
    { "eventId": "vc_001",  "success": true,  "duplicate": true },
    { "eventId": "atc_001", "success": true,  "duplicate": false, "platforms": { "queued": ["meta", "ga4"], "skipped": [] } },
    { "eventId": "ic_001",  "success": true,  "duplicate": false, "platforms": { "queued": ["meta", "ga4"], "skipped": [] } },
    { "eventId": "p_001",   "success": false, "error": "event_not_found" }
  ]
}

Maximum 100 events per request. For larger volumes, split into multiple requests.

Event schema

Each event has three required and three optional fields.

• eventName (Required) — Standard event name (e.g. "Purchase") or the name of a predefined custom event
• eventId (Required) — Unique ID per event — use a stable, business-tied value (e.g. "purchase_<orderId>") for idempotency
• eventTime (Required) — Unix timestamp in seconds, within [now-86400, now+300] — older than 24h or further than 5 minutes in the future → the event is rejected
• sourceUrl (Optional) — Full URL of the page on which the event was triggered
• userData (Optional) — End-customer contact data (email, phone, firstName, lastName, …) — the server hashes per-platform; cleartext never leaves the server
• customData (Optional) — Business data for the event (currency, value, orderId, contentIds, contents, …)

Response flags

The GET response includes two classification flags per event:

• isRecurring — true for recurring orders from subscription apps (Recharge, Bold, Loop, Shopify Subscriptions). Useful for separating first-time and repeat purchases in reports.
• isTest — true for test orders from Bogus Gateway or Shopify Payments Test Mode. Test purchases do not increment the order counter and never trigger plan overage.

Standard events

These eight event names are predefined in ShopiPixel and recognised by all supported platforms out of the box:

PageView, ViewContent, ViewCategory, AddToCart, InitiateCheckout, Purchase, Search, CompleteRegistration

Custom events

Custom event names can be defined upfront in the wizard at /app/event-triggers/events. Once a custom event is active you can trigger it via /api/v1/events.

• Maximum 20 custom events per store
• Event names must be alphanumeric (including underscore), max 64 characters
• Snapchat limits custom events to a maximum of 5 on the platform side

See the "Custom Events" section above for details. Custom Events

GET /api/v1/stats — retrieve statistics

Returns aggregated metrics for a date range: revenue, conversion rate, conversions per platform, and event delivery success rates. The result is always normalised to the store's currency (multi-currency stores are converted via the ECB rate).

Query parameters

Note: with granularity=hour the maximum range is limited to 7 days — hourly aggregates over longer ranges produce too many data points for efficient reporting.

curl -X GET "https://app.shopipixel.de/api/v1/stats?granularity=day&from=2026-04-01&to=2026-05-01" \
  -H "Authorization: Bearer sp_xxxxxxxxxxxx"

const params = new URLSearchParams({
  granularity: "day",
  from: "2026-04-01",
  to: "2026-05-01",
});

const response = await fetch(
  `https://app.shopipixel.de/api/v1/stats?${params}`,
  {
    method: "GET",
    headers: { "Authorization": "Bearer sp_xxxxxxxxxxxx" },
  },
);

const { summary, timeline, platforms } = await response.json();

console.log(`Umsatz: ${summary.totalRevenue} ${summary.currency}`);
console.log(`Conversions: ${summary.totalConversions}`);
console.log(`Conversion-Rate: ${(summary.conversionRate * 100).toFixed(2)}%`);

import requests

response = requests.get(
    "https://app.shopipixel.de/api/v1/stats",
    params={"granularity": "day", "from": "2026-04-01", "to": "2026-05-01"},
    headers={"Authorization": "Bearer sp_xxxxxxxxxxxx"},
)
response.raise_for_status()

payload = response.json()
summary = payload["summary"]

print(f"Umsatz: {summary['totalRevenue']} {summary['currency']}")
print(f"Conversions: {summary['totalConversions']}")
print(f"Conversion-Rate: {summary['conversionRate'] * 100:.2f}%")

<?php
$query = http_build_query([
    "granularity" => "day",
    "from" => "2026-04-01",
    "to" => "2026-05-01",
]);

$ch = curl_init("https://app.shopipixel.de/api/v1/stats?$query");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer sp_xxxxxxxxxxxx",
]);

$response = curl_exec($ch);
curl_close($ch);
$payload = json_decode($response, true);
$summary = $payload["summary"];

echo "Umsatz: {$summary["totalRevenue"]} {$summary["currency"]}\n";
echo "Conversions: {$summary["totalConversions"]}\n";
echo "Conversion-Rate: " . number_format($summary["conversionRate"] * 100, 2) . "%\n";

Response example

{
  "summary": {
    "totalRevenue": 12450.99,
    "currency": "EUR",
    "totalEvents": 18342,
    "totalConversions": 234,
    "conversionRate": 0.0128,
    "averageOrderValue": 53.21
  },
  "timeline": [
    {
      "date": "2026-05-08",
      "pageViews": 1234,
      "purchases": 23,
      "revenue": 1234.56,
      "currency": "EUR"
    }
  ],
  "platforms": {
    "meta": { "eventsSent": 18342, "successRate": 0.987 }
  }
}

Multi-currency note: if your store records orders in multiple currencies, all amounts are converted via the ECB daily rate into the store currency. The response contains the currency field with the target currency.

Rate limits

Each API key has its own rate-limit budget. Server-side caching and bulk operations help spend the budget efficiently.

• 1,000 requests per hour per API key
• Every response includes the headers X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset
• On exceeded limits the server responds with HTTP 429 and a Retry-After header in seconds

Common errors

401 unauthorized

Authorization header is missing, malformed, or contains an invalid, expired or revoked key. For security reasons we do not differentiate between these cases.

403 Permission … required

The key lacks the required permission for this endpoint. Adjust permissions in /app/settings/api or generate a new key.

403 Enterprise plan required

The store is not on the Enterprise plan or the subscription is inactive. Check plan status in the billing area.

413 Request body too large

The request body exceeds 512 KB. Split large bulk requests into smaller ones — ~50 events per request is recommended.

429 Rate limit exceeded

Rate limit exceeded. Wait for the duration in the Retry-After header before retrying. Use exponential backoff for repeated 429s.

Web Pixel & Cookies

What is the Web Pixel?

The ShopiPixel Web Pixel is a Shopify-certified browser extension that is automatically activated upon app installation. It runs in Shopify's Strict Sandbox — the highest security level.

Check Installation

Shopify Admin → Settings → Customer Events → ShopiPixel = "Connected"

Which Cookies Are Set

The following cookies are set only with consent from your customers:

What Data Does the Web Pixel Collect

Only with valid consent:

• Click IDs from ad URLs
• Anonymous browser identifier
• Browser type
• Session identifier
• Consent status

What Data Is NOT Collected

• No IP addresses
• No personal data without consent
• No browsing behavior on other websites
• No fingerprinting

Known Limitations

Privacy & GDPR

Responsibility

• You as the store owner are the data controller (Art. 4(7) GDPR).
• ShopiPixel is your data processor (Art. 28 GDPR).
• A Data Processing Agreement (DPA) is accepted upon app installation.

Processed Data

Legal Basis

• Consent (Art. 6(1)(a) GDPR, §25 TDDDG) for browser cookies and pixel tracking
• Legitimate interest (Art. 6(1)(f) GDPR) for webhook-based processing of order data for conversion measurement
• Contract performance (Art. 6(1)(b) GDPR) for app usage itself

Data Sharing

• Events are sent to the advertising platforms you have configured (Meta, Google, TikTok etc.)
• Data may be transferred to third countries (USA) — basis: EU-US Data Privacy Framework or standard contractual clauses of the respective platform
• ShopiPixel itself does not share data with third parties

Server Location

Germany — all data is processed and stored exclusively on German servers.

Data Subject Rights

Your customers have the right to:

• Access (Art. 15 GDPR)
• Erasure (Art. 17 GDPR)
• Rectification (Art. 16 GDPR)
• Restriction of processing (Art. 18 GDPR)
• Data portability (Art. 20 GDPR)
• Objection (Art. 21 GDPR)

GDPR requests from end customers are processed automatically via Shopify webhooks. When a customer requests access, deletion, or data export, Shopify forwards the request to ShopiPixel — deletions are automatically propagated to all connected platforms.

Text Template for Your Privacy Policy

You can copy the following text into your privacy policy and adapt it to your circumstances:

More Help

Here you'll find links to all help pages and resources: