Shopify server event tracking
Overview
When installed on your Shopify store, Chord sends tracking events from two sources:
- Your storefront, using either the Chord Shopify web pixel or @chordcommerce/analytics (see Shopify installationShopify installation)
- Chord's server events service, which sends tracking events from a Shopify webhook source in your Chord workspace in response to webhook triggers from Shopify
When Chord provisions your workspace, it includes a Shopify webhook source. This source listens for webhook events from Shopify and transforms them into Chord events.
Requirements
Locate the webhook source in your Chord workspace, named "Shopify Webhooks." Chord typically creates this source as part of your workspace provisioning. You will need:
- The settings page of this source during the "Create an Admin API Key" step
- The webhook URL of this source during the "Create Webhook Subscriptions" step
If you cannot find the source or are unsure which one it is, contact [email protected].
Step 1: Create an Admin API Key
Chord's webhook source requires an Admin API key with the read_orders scope to retrieve order details from Shopify. We recommend creating a dedicated custom app in your Shopify account for Chord, which makes it easy to manage access.
Create the API key in Shopify
- In your Shopify Admin, go to Settings > Apps and sales channels > Develop apps > Create an app.
- Name the app (e.g., "Chord Webhooks").
- Click Configure Admin API Scopes.
- Select read_orders only and click Save.
- On the Overview tab, click Install app.
- Copy the Admin API access token.
Add the token to your Chord workspace
- In your Chord workspace, navigate to your Shopify webhook source.
- Open Settings > Connection.
- Enter the Admin API access token in the Access Token field.
- Click Save Changes.
Step 2: Create Webhook Subscriptions
- In your Chord workspace, navigate to your Shopify webhook source.
- Find the webhook URL under the Configure your webhook heading. Copy this URL.
- In your Shopify Admin, go to Settings > Notifications > Webhooks (or use the Shopify Admin API to create subscriptions programmatically — you can use the same Admin API access token you created in Step 1).
- Create a webhook subscription for each of the supported topics listed below. Each subscription should use the same webhook URL you copied from your Chord workspace.
Supported Webhook Topics
Webhook Topic | Chord Event |
|---|---|
checkouts/create | Checkout Created |
orders/create | Order Completed |
refunds/create | Order Refunded |
customers/delete | Customer Deleted |
customers/merge | Customer Merged |
locations/delete | Location Deleted |
orders/delete | Order Deleted |
products/delete | Product Deleted |
Verifying the Installation
Shopify's built-in webhook testing does not send payloads that match real webhook payloads. To verify that server events are flowing correctly:
- Complete a test transaction in your Shopify store.
- In your Chord workspace, navigate to the Shopify webhook source and open the Debugger tab.
- Confirm that the expected events (Checkout Created, Order Completed, etc.) appear.
Subscription Events
If your store sells subscriptions, Chord can also track subscription lifecycle events (creation, cancellation, payment failures, etc.). Due to Shopify platform restrictions, subscription events require a different setup using Shopify Flow.
See Shopify subscription event trackingevent tracking for details.
Associating Server Events with Storefront Sessions
To link server events with front-end storefront events from the same customer session, the storefront must save certain browser identifiers as attributes on the cart or order. These identifiers are then retrieved by the webhook source and included in Chord events.
For details, see Unifying Data Across Sources.