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

# Shopify

> Connect Shopify to OneSignal through the Vendo integration for web push notifications, customer tags, commerce events, and behavioral targeting.

OneSignal has partnered with Vendo to create a seamless Shopify integration. Vendo deploys the OneSignal SDK on your Shopify storefront with one click — no manual theme code editing required. It syncs customer tags, client-side browsing events, and server-side commerce events to OneSignal so you can build segments and trigger push campaigns from real behavior and purchase history.

For Vendo's documentation, see [Vendo OneSignal Destination](https://docs.vendodata.com/destinations/onesignal/overview).

## Prerequisites

Before you begin, make sure you have:

* A Shopify store with the [Vendo app](https://apps.shopify.com/) installed
* A OneSignal account and app (Web platform)
* Your OneSignal **App ID** (required)
* Your OneSignal **REST API Key** (required for server-side events like order syncing and user tagging)
* Vendo app embed enabled in your Shopify theme settings

## OneSignal setup

<Steps>
  <Step title="Create a OneSignal app">
    Log in to [onesignal.com](https://onesignal.com) and create or select an app. Choose **Web** as the platform and select **Custom Code** as the integration type.

    <Warning>
      You must select **Custom Code**. The **Typical Site** option does not expose the service worker path settings, so the SDK will try to load `/OneSignalSDKWorker.js` from your store root — Shopify blocks this and push subscriptions will silently fail. If you already created the app under Typical Site, switch to Custom Code in **Settings > Platforms > Web**, or delete and recreate the app.
    </Warning>
  </Step>

  <Step title="Configure web push settings">
    In your OneSignal app, navigate to **Settings > Push & In-App > Web Settings** or follow the [Web push setup](./web-push-setup) guide.

    **Site setup**

    * **Site Name**: Your store name, used as the default notification title.
    * **Site URL**: Your Shopify store's publicly accessible URL (e.g., `https://yourstore.com`).
      * Must be the exact [origin](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) of your site.
      * Do not use `https://your-site.myshopify.com/` if customers access your site through a custom domain like `https://your-site.com/`.
    * **Default Icon URL**: Upload a square 256x256px PNG image for notification prompts and messages. If not set, a bell icon is used.
  </Step>

  <Step title="Configure the service worker path">
    Shopify does not allow serving files from the site root, so you must tell OneSignal where Vendo serves the service worker file.

    In OneSignal, go to **Settings > Push & In-App > Web Settings**, scroll to **Advanced Push Settings**, and toggle on **Customize service worker paths and filenames**, then configure:

    | Setting                           | Value                   |
    | --------------------------------- | ----------------------- |
    | Path to service worker files      | `/apps/vendo/`          |
    | Main service worker filename      | `OneSignalSDKWorker.js` |
    | Updater service worker filename   | `OneSignalSDKWorker.js` |
    | Service worker registration scope | `/apps/vendo/`          |

    <Frame caption="Service worker configuration for Shopify stores using Vendo.">
      <img src="https://mintcdn.com/onesignal/N_-d1DtCTRgGPN4l/images/integrations/shopify/vendo-service-worker-configuration.png?fit=max&auto=format&n=N_-d1DtCTRgGPN4l&q=85&s=b7bc1794445e002bd3427c94a6ec6ccf" alt="OneSignal Advanced Push Settings showing service worker paths configured for Vendo" width="3038" height="1108" data-path="images/integrations/shopify/vendo-service-worker-configuration.png" />
    </Frame>

    Vendo automatically serves the required `OneSignalSDKWorker.js` file at `https://yourstore.myshopify.com/apps/vendo/OneSignalSDKWorker.js` — no manual file uploads needed.

    <Note>
      The Vendo app's **OneSignal > Push Settings** page displays these exact values with click-to-copy, so you don't need to retype them.

      The Updater Filename and Main Service Worker Filename are the same file. OneSignal v16+ uses a single service worker for both purposes.
    </Note>
  </Step>

  <Step title="Copy your credentials">
    In OneSignal, go to [**Settings > Keys & IDs**](./keys-and-ids) and copy your **App ID** and **REST API Key**. You will enter these in Vendo.
  </Step>
</Steps>

## Vendo setup

<Steps>
  <Step title="Install the Vendo app">
    Install the Vendo app from the Shopify App Store.
  </Step>

  <Step title="Add the OneSignal integration">
    In Vendo, navigate to **Destinations > OneSignal**.

    <Frame caption="Add the OneSignal integration in Vendo.">
      <img src="https://mintcdn.com/onesignal/PoskQI_qr0DD8jDV/images/integrations/shopify/vendo-onesignal-integrations.png?fit=max&auto=format&n=PoskQI_qr0DD8jDV&q=85&s=13acfaf4e6b01f77535f1a1386c4212d" alt="Vendo Integrations page showing the OneSignal integration option" width="2520" height="1756" data-path="images/integrations/shopify/vendo-onesignal-integrations.png" />
    </Frame>
  </Step>

  <Step title="Enter your OneSignal credentials">
    Enter your OneSignal **App ID** and **REST API Key** from the previous section, then click **Save**.
  </Step>

  <Step title="Enable the Vendo theme block">
    The Vendo theme block loads the OneSignal SDK on your storefront. Without it, the push prompt will not appear and client-side tracking will not work.

    1. In your Shopify admin, go to **Online Store > Themes > Customize**.
    2. Click **App embeds** (puzzle piece icon in the left sidebar).
    3. Toggle **Vendo** on.
    4. Click **Save**.

    The theme block handles SDK initialization, service worker registration, push prompt display, user identification (push subscription, login, newsletter signup), and tag syncing for identified users.
  </Step>

  <Step title="Select events to sync">
    In the Vendo app under **OneSignal > Events**, enable the client-side and server-side events you want to send to OneSignal. See [Tracking](#tracking) below for the full event list.
  </Step>

  <Step title="Configure push prompts">
    Whether each prompt appears on your storefront — and when — is controlled from the Vendo app, not the OneSignal dashboard. In the Vendo app, open **OneSignal > Push Settings**. You will see four sections, each with its own toggle:

    | Section                   | What it does                                                   |
    | ------------------------- | -------------------------------------------------------------- |
    | **Subscription Bell**     | Floating bell icon visitors can click to subscribe at any time |
    | **Push Slide Prompt**     | Branded slide-in banner asking for push permission             |
    | **Native Browser Prompt** | Triggers the browser's built-in permission dialog directly     |
    | **Welcome Notification**  | Push notification sent automatically when a visitor subscribes |

    For Push Slide and Native prompts, you also set **triggers** — how many page views and how many seconds to wait before the prompt fires. Sensible defaults are pre-filled.

    All four prompts are **off by default** — enable only the ones you want. Save once at the bottom of the page; changes take effect on the next storefront load without a theme redeploy.

    <Note>
      Prompt button copy, action message text, icons, and advanced options like A/B tests and localization are configured in the OneSignal dashboard. From Vendo's Push Settings, click **Open OneSignal Dashboard** to jump directly to the Permission Prompt Setup page. If a prompt is configured in OneSignal's dashboard but its Vendo toggle is off, it will not render — Vendo's toggle is the source of truth for visibility.
    </Note>
  </Step>

  <Step title="Historical data sync (optional)">
    Vendo can backfill existing customers and recent order history to OneSignal. This happens automatically in the background after you save your credentials.

    <Frame caption="Historical data sync options in Vendo.">
      <img src="https://mintcdn.com/onesignal/dknFSNQuQfw5IM0j/images/integrations/shopify/vendo-historical-data.png?fit=max&auto=format&n=dknFSNQuQfw5IM0j&q=85&s=4eb61a384a7ac3f4596661348f98ac48" alt="Vendo historical data settings showing sync options for Shopify data" width="1724" height="762" data-path="images/integrations/shopify/vendo-historical-data.png" />
    </Frame>
  </Step>
</Steps>

## Tracking

### User identification

Vendo uses an **identified-only** approach — anonymous visitors are not tracked in OneSignal. Users must be identified through one of four methods before events are sent. This prevents duplicate users and ensures clean, actionable data.

| Method                    | How it works                                                                                                               | Identifier used              |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| **Web push subscription** | Visitor clicks "Allow" on the push prompt. OneSignal creates a user automatically and Vendo captures the OneSignal ID.     | OneSignal ID                 |
| **Newsletter signup**     | Visitor submits a newsletter or email form. Vendo captures the email and calls `OneSignal.login(email)`.                   | Email                        |
| **Customer login**        | Customer logs into their Shopify account. Vendo detects this and calls `OneSignal.login()` with the configured identifier. | Shopify Customer ID or Email |
| **Checkout completed**    | Customer completes a purchase. Vendo stores the identifier and calls `OneSignal.login()`.                                  | Shopify Customer ID or Email |

<Warning>
  If you have a mobile app or third-party connections, select the identifier (Shopify Customer ID vs. Email) that matches your other tools so user profiles stay consistent across platforms. Configure this in the Vendo app under **Settings > Customer Identifier**.
</Warning>

#### Identity merging

If a push subscriber (identified by OneSignal ID) later logs in or completes a purchase, Vendo calls `OneSignal.login()` with their Shopify Customer ID or email. OneSignal links the push subscription to the identified user — no duplicate users are created. All past push subscriptions are preserved, and server-side events (orders, fulfillments) reach the correct user profile.

### Customer tags

Vendo syncs customer properties as [tags](./add-user-data-tags) in OneSignal for segmentation. All values are stored as strings (OneSignal's native format).

#### Identity & profile

| Tag                   | Description                                     |
| --------------------- | ----------------------------------------------- |
| `email`               | Customer email                                  |
| `first_name`          | First name                                      |
| `last_name`           | Last name                                       |
| `phone`               | Customer phone number                           |
| `shopify_customer_id` | Shopify customer ID                             |
| `verified_email`      | `"true"` or `"false"`                           |
| `tax_exempt`          | `"true"` or `"false"`                           |
| `customer_tags`       | Comma-separated Shopify tags                    |
| `customer_created_at` | Customer creation date (ISO 8601)               |
| `first_seen`          | ISO timestamp of the first identification event |

#### Marketing consent

| Tag                       | Description                     |
| ------------------------- | ------------------------------- |
| `marketing_state`         | Overall marketing consent state |
| `email_marketing_consent` | Email marketing consent state   |

#### Commerce stats

| Tag                | Description                       |
| ------------------ | --------------------------------- |
| `total_spent`      | Lifetime spend                    |
| `order_count`      | Total orders                      |
| `first_order_date` | First order date (ISO 8601)       |
| `last_order_date`  | Most recent order date (ISO 8601) |

#### Attribution tags

Vendo captures UTM parameters and click IDs at checkout and syncs them as tags. Last-touch values are overwritten on each checkout; first-touch values (`initial_utm_*`) are written only once.

| Tag                    | Description                         |
| ---------------------- | ----------------------------------- |
| `utm_source`           | Last-touch UTM source               |
| `utm_medium`           | Last-touch UTM medium               |
| `utm_campaign`         | Last-touch UTM campaign             |
| `utm_content`          | Last-touch UTM content              |
| `utm_term`             | Last-touch UTM term                 |
| `initial_utm_source`   | First-touch UTM source (set once)   |
| `initial_utm_medium`   | First-touch UTM medium (set once)   |
| `initial_utm_campaign` | First-touch UTM campaign (set once) |
| `gclid`                | Google Ads click ID                 |
| `fbclid`               | Meta (Facebook/Instagram) click ID  |
| `ttclid`               | TikTok click ID                     |
| `msclkid`              | Microsoft Ads click ID              |

#### Segment membership

Vendo can sync Shopify segment membership as tags in the format `shopify_segment_{segment_id}` with a value of `"true"`. See [Vendo's Events & Properties reference](https://docs.vendodata.com/destinations/onesignal/events-and-properties) for details on running the sync.

### Client-side events

Vendo tracks client-side [custom events](./custom-events) on your storefront via the Shopify Web Pixel and sends them to OneSignal. These events are only sent after a user is identified.

| Event                              | Description                                                    |
| ---------------------------------- | -------------------------------------------------------------- |
| `page_viewed`                      | Customer visits a page (storefront, checkout, or order status) |
| `product_viewed`                   | Customer views a product details page                          |
| `collection_viewed`                | Customer views a product collection page                       |
| `search_submitted`                 | Customer performs a storefront search                          |
| `product_added_to_cart`            | Product is added to cart                                       |
| `product_removed_from_cart`        | Product is removed from cart                                   |
| `cart_viewed`                      | Customer views the cart page                                   |
| `checkout_started`                 | Customer starts checkout                                       |
| `checkout_contact_info_submitted`  | Contact info step submitted                                    |
| `checkout_address_info_submitted`  | Address info step submitted                                    |
| `checkout_shipping_info_submitted` | Shipping method selected                                       |
| `payment_info_submitted`           | Payment details submitted                                      |
| `checkout_completed`               | Checkout completed successfully                                |
| `alert_displayed`                  | Checkout alert or warning displayed                            |
| `ui_extension_errored`             | Checkout UI extension runtime error                            |
| `all_custom_events`                | Custom Shopify customer events                                 |

<Frame caption="Client-side event configuration in Vendo.">
  <img src="https://mintcdn.com/onesignal/dknFSNQuQfw5IM0j/images/integrations/shopify/vendo-client-side-events.png?fit=max&auto=format&n=dknFSNQuQfw5IM0j&q=85&s=c94b99465b8c200ebb1bb475e492f8a1" alt="Vendo client-side events settings showing available custom events" width="865" height="726" data-path="images/integrations/shopify/vendo-client-side-events.png" />
</Frame>

### Server-side events

Shopify commerce events are exported and forwarded to OneSignal through the Vendo pipeline. These always use the Shopify Customer ID as the `external_id`.

| Event                      | Description                 |
| -------------------------- | --------------------------- |
| `order_received`           | New order is created        |
| `order_fulfilled`          | Order is fulfilled/shipped  |
| `order_delivered`          | Order is delivered          |
| `order_refunded`           | Order is fully refunded     |
| `order_partially_refunded` | Order is partially refunded |
| `cart_abandoned`           | Checkout is abandoned       |

<Frame caption="Server-side event configuration in Vendo.">
  <img src="https://mintcdn.com/onesignal/dknFSNQuQfw5IM0j/images/integrations/shopify/vendo-server-side-events.png?fit=max&auto=format&n=dknFSNQuQfw5IM0j&q=85&s=c9bed30c26b0bec3b8a53eb8cde8098d" alt="Vendo server-side events settings showing available Shopify webhook events" width="865" height="394" data-path="images/integrations/shopify/vendo-server-side-events.png" />
</Frame>

## Platform details

| Setting       | Value                                       |
| ------------- | ------------------------------------------- |
| Sync method   | Client + server-side via Vendo              |
| Identity      | Shopify Customer ID, Email, or OneSignal ID |
| Deduplication | UUID v5 hashing per event                   |
| Batch size    | 1,000 events per request                    |
| Data format   | All values stored as strings                |

## Use cases

### Abandoned cart recovery

Create a [Journey](./journeys-overview) triggered by the `cart_abandoned` event. Wait 1 hour after abandonment, then send a push notification with the recovery link using the `checkout_url` property.

### Order status updates

Create Journeys for `order_fulfilled` and `order_delivered` to send immediate push notifications with tracking information when orders ship and arrive.

### VIP customer engagement

Create a [segment](./segmentation) where `total_spent` is greater than a threshold, then send exclusive offers personalized with the `first_name` tag.

### Re-engagement campaigns

Target inactive customers by creating a segment where `last_order_date` is more than 90 days ago and send win-back campaigns.

## Compatible sources

OneSignal works with the following Vendo data sources:

| Source    | Events      | User tags   | Audiences   |
| --------- | ----------- | ----------- | ----------- |
| Shopify   | Yes         | Yes         | Yes         |
| Stripe    | Coming Soon | Coming Soon | Coming Soon |
| Mixpanel  | Coming Soon | Coming Soon | Coming Soon |
| Amplitude | Coming Soon | Coming Soon | Coming Soon |

***

## Testing

<Steps>
  <Step title="Verify the service worker">
    Visit `https://yourstore.myshopify.com/apps/vendo/OneSignalSDKWorker.js` in your browser. You should see JavaScript code. If you get a 404, verify the Vendo app is installed and the theme block is enabled.

    You can also open browser DevTools (**F12**), go to **Application > Service Workers**, and confirm `OneSignalSDKWorker.js` is registered with a scope of `/apps/vendo/`.
  </Step>

  <Step title="Test the push prompt">
    Open your storefront in an incognito/private window. You should see the OneSignal notification permission prompt. Click **Allow** to subscribe.
  </Step>

  <Step title="Send a test notification">
    In the OneSignal dashboard, go to **Messages > New Push**. Send a test notification to your subscriber and verify it appears.
  </Step>

  <Step title="Verify user data in OneSignal">
    Go to **Audience > All Users** and confirm your test user appears. Check that user tags (email, name, etc.) are syncing for identified users.
  </Step>

  <Step title="Trigger a test event">
    Browse a product or complete a test checkout on your store. Confirm the event appears in the user's activity in the OneSignal dashboard.
  </Step>
</Steps>

***

## Troubleshooting

### Service worker returns 404

The service worker must be at `/apps/vendo/OneSignalSDKWorker.js`. If you see a 404 error at the root path (`/OneSignalSDKWorker.js`), the service worker path is not configured in OneSignal — follow the [service worker configuration step](#configure-the-service-worker-path). If the 404 is at the `/apps/vendo/` path, verify the Vendo app is installed and the theme block is enabled.

### "Typical Site" was selected during OneSignal setup

Vendo requires the **Custom Code** integration type. Typical Site does not expose the service worker path settings, so the SDK will try to load `/OneSignalSDKWorker.js` from your store root — Shopify blocks that and push subscriptions will silently fail.

Fix: in the OneSignal dashboard, either switch the app's integration type to Custom Code under **Settings > Platforms > Web**, or delete the app and recreate it using Custom Code from the start.

### Push prompt not appearing

* Check that the Vendo theme block is enabled in **App embeds**.
* In the Vendo app under **OneSignal > Push Settings**, confirm at least one prompt toggle (Subscription Bell, Push Slide Prompt, or Native Browser Prompt) is turned on — all four are off by default.
* Check the trigger delay — a Push Slide set to multiple page views won't fire on the first page load.
* Verify your browser allows notifications (click the lock icon in the address bar).
* Try an incognito/private window in case the prompt was previously dismissed.

### Tags not appearing in OneSignal

Tags only sync for identified users — anonymous visitors are not tracked. Ensure the user has been identified via push subscription, login, newsletter signup, or checkout. Initial tag syncs can take several hours.

### Events not triggering

Verify events are enabled in the Vendo app under **OneSignal > Events**. Client-side events require the Shopify Web Pixel to be active and the user to be identified. Server-side events require the REST API Key to be configured.

### Notifications show "Delivered" but don't appear

The integration is working — the issue is with your browser or OS notification settings. Check your OS notification settings for your browser, ensure Do Not Disturb / Focus mode is off, and verify browser-level notification permissions.

***

## FAQ

### Can I change the customer identifier after setup?

Yes. Update the setting in the Vendo app under **Settings > Customer Identifier**. Changing the identifier may create separate user profiles if existing users were already identified with the previous method.

### Does the Vendo integration support mobile apps?

The Vendo integration focuses on Shopify storefronts and web push. If you also have a mobile app, ensure the identifier you select in Vendo matches the one you use in your mobile app so user profiles stay consistent.

### What happens if a visitor is never identified?

Events from unidentified visitors are not sent to OneSignal. Once the visitor identifies themselves (by subscribing to push, logging in, signing up for a newsletter, or completing checkout), Vendo begins sending events. This identified-only approach prevents duplicate users and ensures clean data.

### Why does Vendo use an identified-only approach?

Tracking anonymous visitors creates duplicate OneSignal users that can never be properly merged, leading to inflated user counts and fragmented data. The identified-only approach ensures every OneSignal user is real and actionable.

***

## Related pages

<Columns cols={2}>
  <Card title="Keys & IDs" icon="key" href="./keys-and-ids">
    Find your OneSignal App ID and REST API key.
  </Card>

  <Card title="Custom events" icon="bolt" href="./custom-events">
    Track user behavior and trigger automations based on Shopify events.
  </Card>

  <Card title="Web push setup" icon="globe" href="./web-push-setup">
    Set up web push notifications for your Shopify store.
  </Card>

  <Card title="Web permission prompts" icon="bell" href="./permission-requests">
    Configure how and when to prompt visitors for web push permission.
  </Card>
</Columns>