Prerequisites
Before you begin, make sure you have:- A Shopify store with the Vendo app 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)
OneSignal setup
Create a OneSignal app
Log in to onesignal.com and create or select an app. Choose Web as the platform and select Custom Code as the integration type.
Configure web push settings
In your OneSignal app, navigate to Settings > Push & In-App > Web Settings or follow the 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 of your site.
- Do not use
https://your-site.myshopify.com/if customers access your site through a custom domain likehttps://your-site.com/.
- Default Icon URL: Upload a square 256x256px PNG or JPG image for notification prompts and messages. If not set, a bell icon is used.
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 configure:
| Setting | Value |
|---|---|
| Service Worker Path | /apps/vendo/ |
| Service Worker Filename | OneSignalSDKWorker.js |
| Updater Filename | OneSignalSDKWorker.js |
| Service Worker Registration Scope | /apps/vendo/ |
OneSignalSDKWorker.js file at https://yourstore.myshopify.com/apps/vendo/OneSignalSDKWorker.js — no manual file uploads needed.The Updater Filename and Service Worker Filename are the same file. OneSignal v16+ uses a single service worker for both purposes.
Copy your credentials
In OneSignal, go to Settings > Keys & IDs and copy your App ID and REST API Key. You will enter these in Vendo.
Vendo setup
Add the OneSignal integration
In Vendo, navigate to Integrations > Add Integration > OneSignal (or Destinations > OneSignal).
Enter your OneSignal credentials
Enter your OneSignal App ID and REST API Key from the previous section, then click Save.
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.
- In your Shopify admin, go to Online Store > Themes > Customize.
- Click App embeds (puzzle piece icon in the left sidebar).
- Toggle Vendo on.
- Click Save.
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 below for the full event list.
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). | |
| 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 |
Identity merging
If a push subscriber (identified by OneSignal ID) later logs in or completes a purchase, Vendo callsOneSignal.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 in OneSignal for segmentation. All values are stored as strings (OneSignal’s native format).| Tag | Description |
|---|---|
email | Customer email |
first_name | First name |
last_name | Last name |
total_spent | Lifetime spend |
order_count | Total orders |
verified_email | "true" or "false" |
tax_exempt | "true" or "false" |
marketing_state | Marketing consent state |
first_order_date | First order date (ISO 8601) |
last_order_date | Most recent order date (ISO 8601) |
customer_created_at | Customer creation date |
customer_tags | Comma-separated Shopify tags |
email_marketing_consent | Marketing opt-in state |
Client-side events
Vendo tracks client-side 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 |
Server-side events
Shopify commerce events are exported and forwarded to OneSignal through the Vendo pipeline. These always use the Shopify Customer ID as theexternal_id.
| Event | Description |
|---|---|
received_orders | New order is created |
fulfilled_orders | Order is fulfilled/shipped |
delivered_orders | Order is delivered |
refunded_orders | Order is fully refunded |
partially_refunded_orders | Order is partially refunded |
abandoned_checkouts | Checkout is abandoned |
Common event properties
All events include these properties (as strings):| Property | Description |
|---|---|
order_id | Display order identifier |
shopify_order_id | Shopify internal order ID |
email | Customer email |
currency | Order currency |
source | Event source |
version | Integration version |
Data sync frequency
| Data type | Sync frequency |
|---|---|
| Customer tags | Every 4–6 hours |
| Order events | Near real-time (within minutes) |
| Abandoned carts | Every 1–2 hours |
| Fulfillment events | Near real-time |
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 triggered by theabandoned_checkouts 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 forfulfilled_orders and delivered_orders to send immediate push notifications with tracking information when orders ship and arrive.
VIP customer engagement
Create a segment wheretotal_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 wherelast_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 | Yes | Yes | Yes |
| Mixpanel | — | — | Yes |
| Segment | — | — | Yes |
| Amplitude | — | — | Yes |
Testing
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.You can also open browser DevTools (F12), go to Application > Service Workers, and confirm OneSignalSDKWorker.js is registered with a scope of /apps/vendo/.Test the push prompt
Open your storefront in an incognito/private window. You should see the OneSignal notification permission prompt. Click Allow to subscribe.
Send a test notification
In the OneSignal dashboard, go to Messages > Push > New Message. Send a test notification to your subscriber and verify it appears.
Verify user data in OneSignal
Go to Audience > Subscriptions and confirm your test subscription appears. Check that user tags (email, name, etc.) are syncing for identified users.
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. If the 404 is at the /apps/vendo/ path, verify the Vendo app is installed and the theme block is enabled.
Push prompt not appearing
Check that the Vendo theme block is enabled in App embeds. 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?
Previous versions tracked anonymous visitors using Shopify’s session cookie as an identifier. This created duplicate OneSignal users that could 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
Keys & IDs
Find your OneSignal App ID and REST API key.
Custom events
Track user behavior and trigger automations based on Shopify events.
Web push setup
Set up web push notifications for your Shopify store.
Web permission prompts
Configure how and when to prompt visitors for web push permission.