> For the complete documentation index, see [llms.txt](https://docs.webtonative.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.webtonative.com/javascript-apis/webtonative-notifications/webhook-connectors/shopify-connector.md).

# Shopify Connector

Send automatic push notifications to your app users when something happens in your Shopify store, like a new order, a payment or a shipment.

This guide connects your Shopify store to WebToNative with a webhook, and links each logged-in customer to their device so every notification reaches the right person.

> **Platform support:** Android and iOS.

> **Before you start:**
>
> * Your plan must include **WebToNative Push**.
> * Push must be configured for your app (Android and/or iOS) in the WebToNative dashboard.
> * You need access to your Shopify admin (**Settings** and **Online Store > Themes**).

***

## How it works

1. **Link customers to devices.** A small script in your theme calls `WTN.Notification.setExternalUserId()` with the Shopify customer ID when a customer is logged in, and `removeExternalUserId()` when they log out.
2. **Shopify sends a webhook.** When the event happens (for example, an order is created), Shopify sends the order data to your connector's webhook URL.
3. **WebToNative sends the notification.** We read the customer ID from the webhook (`customer.id`) and send your notification to every device linked to that customer.

***

## 1. Add the user sync script to your theme

### Step 1: Open the theme code

1. In Shopify admin, go to **Online Store > Themes**.
2. Click **⋯** next to your current theme and choose **Edit code**.
3. Open **layout/theme.liquid**.

### Step 2: Paste the script

Paste this script on the line just above `</head>`, then click **Save**.

```liquid
<script src="https://unpkg.com/webtonative@1.1.24/webtonative.min.js" defer></script>
<script>
window.addEventListener('load', function () {
  {% if customer %}
  WTN.Notification.setExternalUserId("{{ customer.id }}");
  {% endif %}
});

// Remove the external ID when the customer clicks logout
document.addEventListener('click', function (e) {
  var link = e.target.closest('a[href*="/account/logout"], a[href*="{{ routes.account_logout_url }}"]');
  if (!link || !window.WTN || !WTN.Notification) return;
  e.preventDefault();
  WTN.Notification.removeExternalUserId();
  setTimeout(function () { window.location.href = link.href; }, 300);
});
</script>
```

**What the script does:**

| When                                | Action                                                    |
| ----------------------------------- | --------------------------------------------------------- |
| A logged-in customer opens any page | `setExternalUserId(customer.id)` links them to the device |
| A guest opens a page                | Nothing                                                   |
| The customer taps a logout link     | `removeExternalUserId()` unlinks them, then logs out      |

> **Customers who were already logged in** are linked the next time they open or refresh a page in the app. They don't need to log in again.

> **Use SDK version 1.1.23 or later.** `setExternalUserId` and `removeExternalUserId` are not available in older versions. Make sure your theme doesn't load another, older copy of the WebToNative SDK, because it would replace the newer one.

> **Paste it in theme.liquid only.** Liquid doesn't run in **Settings > Customer events** or in checkout settings. If you switch themes, add the script to the new theme too.

***

## 2. Create the connector in WebToNative

### Step 1: Open Webhook Connector

1. Log in to the WebToNative dashboard.
2. Go to **My Apps** and select your app.
3. In the sidebar, open **Push Notification > Webhook Connector**.

<figure><img src="https://46162361-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MbRbEDU7JrvMAgg52AY%2Fuploads%2FShRmDDM4hA5E7kp8t3nA%2Fwebhook-connector-page.png?alt=media&amp;token=ba1c8d81-a2d2-4f21-839c-ff7105e1a398" alt=""><figcaption></figcaption></figure>

### Step 2: Add a Shopify connector

1. Click **+ Connect Webhook** (or **+ Add Connector** if you already have connectors).
2. Select **Shopify** and click **Continue**.

<figure><img src="https://46162361-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MbRbEDU7JrvMAgg52AY%2Fuploads%2F3fsTivAxFALIZ0hwOgjK%2Fwebhook-connector-choose-platform.png?alt=media&amp;token=2012ae95-ec9b-4c8d-811e-f23f2dfe3ef4" alt=""><figcaption></figcaption></figure>

&#x20;3\.  Enter a \*\*Connector Name\*\*, for example \`Order created\`. 4. Copy the \*\*Webhook URL\*\*.

Keep this window open. You'll come back to paste the secret and click **Verify**.

***

## 3. Create the webhook in Shopify

### Step 1: Open Shopify webhooks

1. In Shopify admin, go to **Settings > Notifications**.
2. Scroll to the bottom and open **Webhooks**.

### Step 2: Create the webhook

1. Click **Create webhook**.
2. Fill in the form:

| Field           | Value                                                  |
| --------------- | ------------------------------------------------------ |
| **Event**       | The event this connector is for, e.g. `Order creation` |
| **Format**      | `JSON`                                                 |
| **URL**         | The **Webhook URL** from your connector                |
| **API version** | The latest version                                     |

3. Click **Save**.

### Step 3: Copy the signing secret

Below the webhook list, Shopify shows **"Your webhooks will be signed with …"**. Copy that secret.

> Shopify uses **one signing secret for all webhooks** in your store. Every Shopify connector uses the same secret.

***

## 4. Verify the connector

### Step 1: Paste the secret and click Verify

1. Back in WebToNative, paste the signing secret into **Secret Code**.
2. Tick **Yes, I have created the webhook in Shopify and pasted its secret code here**.
3. Click **Verify**.

<figure><img src="https://46162361-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MbRbEDU7JrvMAgg52AY%2Fuploads%2FNlsqqGrolxYknDUouFlR%2Fshopify-add-connector-secret.png?alt=media&amp;token=b01820bf-28c8-455c-b61b-9f66289b1555" alt=""><figcaption></figcaption></figure>

The connector is saved and the window shows **Waiting for the test event**.

### Step 2: Send a test webhook from Shopify

1. In Shopify admin, go back to **Settings > Notifications > Webhooks**.
2. Click **⋯** next to your webhook and choose **Send test notification**.

<figure><img src="https://46162361-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MbRbEDU7JrvMAgg52AY%2Fuploads%2FoOlPADkNWVDRRP1CY08j%2Fshopify-waiting-for-test-event.png?alt=media&amp;token=8cb1aa9b-3da6-4372-a8f1-c549828b34b1" alt=""><figcaption></figcaption></figure>

When WebToNative receives the test and the secret matches, the connector status changes to **Active**.

> **You can close this window.** The connector stays in the list as **Pending verification** and verifies automatically once the test event arrives. No notifications are sent until it's **Active**.

> **One connector = one webhook.** To send notifications for another event (for example, Order fulfillment), add a new connector and create another Shopify webhook with that connector's URL. Use the same signing secret.

***

## 5. Create the notification template

After the connector is verified, the **Create a Template** window opens. You can also open it later from the **⋯** menu on the connector row > **Edit Template**.

1. **Connector Name** is filled in and can't be changed here.
2. Enter a **Title** for the notification.
3. Enter the **Message**. Click **Available variables** `{ }` to insert values from the webhook.
4. Enter a **Launch URL**: the page that opens when the user taps the notification (optional). It can be a fixed URL, like `https://yourstore.com/orders`, or a variable.
5. Check the phone preview, then click **Save Template**.

<figure><img src="https://46162361-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MbRbEDU7JrvMAgg52AY%2Fuploads%2F3eKOvdtZMziXlm7yxTho%2Fcreate-template.png?alt=media&amp;token=c05cfc28-6111-4586-b16c-f88e53ac3d30" alt=""><figcaption></figcaption></figure>

### Using variables

Insert values from the Shopify webhook with `{{field}}`. Open **Available variables** in the template to pick one.

| Variable                  | Value from Shopify         | Example         |
| ------------------------- | -------------------------- | --------------- |
| `{{id}}`                  | Order ID                   | `5501234567890` |
| `{{name}}`                | Order number               | `#1001`         |
| `{{total_price}}`         | Order total                | `1499.00`       |
| `{{currency}}`            | Currency                   | `INR`           |
| `{{financial_status}}`    | Payment status             | `paid`          |
| `{{customer.id}}`         | Customer ID                | `7012345678901` |
| `{{customer.first_name}}` | Customer first name        | `Asha`          |
| `{{order_status_url}}`    | Customer order status page | `https://…`     |

**Example:**

* Title: `Order received`
* Message: `Hi {{customer.first_name}}, your order {{name}} of {{currency}} {{total_price}} is confirmed.`
* Launch URL: `{{order_status_url}}`

***

## 6. Manage your connectors

### Connector status

| Status                   | Meaning                                                                            |
| ------------------------ | ---------------------------------------------------------------------------------- |
| **Pending verification** | Created, but not verified yet. No notifications are sent.                          |
| **Active**               | Verified and sending notifications.                                                |
| **Paused**               | Turned off with the **Enabled** toggle. Webhooks are received but nothing is sent. |

### Row actions

Open the **⋯** menu on a connector row:

* **Analytics**: Events Received, Notification Sent, Notification Skipped and CTR for this connector.
* **Edit Template**: change the title, message or Launch URL.
* **Delete**: remove the connector. Also delete its webhook in Shopify.

Use the **Enabled** toggle to pause or resume a connector.

***

## 7. Troubleshooting

* **Connector stays Pending verification**
  * Click **Verify** first, then send the test notification from Shopify (**⋯ > Send test notification**).
  * Copy the signing secret again from **Settings > Notifications > Webhooks** and paste it without extra spaces.
  * Make sure the webhook URL in Shopify is exactly the one from your connector.
* **"You don't have any users yet" banner**
  * Add the user sync script to **layout/theme.liquid**.
  * Log in on the app once so the customer is linked to the device.
* **`setExternalUserId is not a function`**
  * An older WebToNative SDK is loaded on the page. Use version 1.1.23 or later and remove older script tags.
* **Notification Skipped increases**
  * The order was a guest checkout, so there is no customer to send it to.
  * The customer hasn't opened the app while logged in, so their device isn't linked yet.
  * The connector is **Paused**, or it has no template.
* **Customer still receives notifications after logout**
  * The customer logged out from Shopify's hosted account page, where the theme script doesn't run. They're unlinked the next time they tap the store's logout link, or replaced when another customer logs in on the device.

***

**Notes:**

* Notifications are sent only to customers who are logged in on the app at least once with the script installed.
* The customer ID in the webhook (`customer.id`) must match the ID linked by the script. This works automatically with the script above.
* Need help? Email <support@webtonative.com> or visit [webtonative.com/support](https://www.webtonative.com/support).
