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

# Shopify integration

> Set up the Shopify Cometly integration: install the pixel and add an order payment webhook so every paid order is tied to the ad that produced it.

The Shopify Cometly integration tracks your Shopify purchases using webhooks, so your conversion events are sent automatically when an order is paid. You install the Cometly pixel (the tracking script on your store), create a Shopify webhook, and map the webhook payload into a **Purchase** event in Cometly. An event is an action Cometly tracks, such as a lead or a purchase.

This matters because Cometly can only attribute the orders it receives. Once each paid order arrives with the visitor's identity, you can see which campaign, ad set and ad produced each sale and how much revenue it brought in.

> [!NOTE]
>
> The **Integrations** page in Cometly also has a **Shopify** card that connects with your Shopify store URL and an Admin API access token. This guide covers the webhook method.

## How the Shopify Cometly integration works

Here is the idea in plain terms:

* You install the **Cometly pixel** on your Shopify store so Cometly can identify each visitor using a unique token called `comet_token` (plus a fingerprint).
* When someone places an order and payment is captured, Shopify sends a **webhook** (a message) to Cometly with the order details.
* Inside Cometly, you map the Shopify data (name, email, amount, `comet_token` and so on) into your **Purchase** event.
* That gives you accurate attribution and also lets you power server-side tracking like the **Meta Conversion API (CAPI)** and **Google Conversion API** if you want.

> [!WARNING]
>
> The `comet_token` and `fingerprint` only show up in the webhook payload when the Cometly pixel was installed at the time the customer placed the order.

### Why this matters

Shopify webhooks give Cometly a reliable "order paid" signal.

When you also pass `comet_token`, `fingerprint` and `IP`, Cometly can match purchases back to the exact visitor journey, which improves attribution accuracy and match rates in ad platforms.

## Step 1: Install the Cometly pixel in Shopify

You must install the Cometly pixel first so Shopify orders contain the visitor identity data needed for accurate matching.

Follow the [Shopify pixel installation guide](https://docs.cometly.com/integrations/pixel/shopify.md).

**What to do**

* Add the **Cometly pixel** before the closing `</head>` tag in your `theme.liquid`.

**What this does**

* The Cometly pixel automatically generates and stores the following tracking attributes on your orders:

  * `comet_token`
  * `fingerprint`

These become available later when you map your Shopify webhook into Cometly.

> [!TIP]
>
> Install the pixel first, then place a fresh test order after installation. Older orders will not contain the correct visitor identity fields.

## Step 2: Create a Purchase webhook in Cometly

Now you create a webhook event in Cometly and copy the webhook URL you will paste into Shopify. The [webhooks guide](https://docs.cometly.com/integrations/webhooks.md) covers this flow in more detail.

1. In Cometly, click **Events Manager** in the sidebar.
2. Click **Create Event**.
3. Under **App / Integration**, select **Webhooks**.
4. Select **Purchase** as the event name.
5. Click **Create**. The event appears in the Events Manager as a draft.
6. Click **Configure** on the draft event, then click **Copy** next to **Your webhook URL**.

> [!NOTE]
>
> Keep this tab open. You paste this URL into Shopify in the next step.

## Step 3: Create the webhook in Shopify

You are going to tell Shopify to send an event to Cometly whenever an order payment happens.

1. In Shopify, click **Settings** (bottom left).

2. Click **Notifications**.

   ![Shopify settings menu with an arrow pointing to Notifications](https://mintcdn.com/cometly/alvP4_0ekdK-CBm_/images/integrations/platforms/shopify/01.webp?fit=max\&auto=format\&n=alvP4_0ekdK-CBm_\&q=85\&s=bc54ea85181fc06f724cd0b06de78ad0)

3. Click **Webhooks**.

4. Click **Create webhook**.

   ![Shopify Webhooks page with an arrow pointing to the Create webhook button](https://mintcdn.com/cometly/alvP4_0ekdK-CBm_/images/integrations/platforms/shopify/03.webp?fit=max\&auto=format\&n=alvP4_0ekdK-CBm_\&q=85\&s=0c68ab3c40caeba611dbd42080fdb80c)

5. Configure the webhook like this:

   * **Event:** `Order payment` (the paid order event)
   * **Format:** `JSON`
   * **URL:** Paste your Cometly webhook URL
   * **Webhook API version:** Whichever version is marked (Latest)

   ![Shopify Add webhook dialog with Event set to Order payment, Format JSON and the latest API version](https://mintcdn.com/cometly/alvP4_0ekdK-CBm_/images/integrations/platforms/shopify/04.webp?fit=max\&auto=format\&n=alvP4_0ekdK-CBm_\&q=85\&s=65e937b5702cbb9174391dc982b76434)

6. Click **Save**.

## Step 4: Map Shopify webhook data into your Cometly Purchase event

Now that Shopify is sending the payload, you need to map the payload fields into the right Cometly fields so attribution and match rates are strong.

Back on the Cometly tab, click **Check for Data**, select a record once Shopify has sent one, and click **Continue With Selected Record** to reach the mapping step. See the [webhooks guide](https://docs.cometly.com/integrations/webhooks.md) for how mapping works.

### Required mappings for accurate tracking

On the mapping step, make sure you map all of the following Cometly fields:

* **First Name**
* **Last Name**
* **Email**
* **Phone**
* **Amount**: the purchase amount. You can use **Formatting Options** to adjust the amount, for example to deduct taxes and shipping.
* **IP**
* **Comet Token** (the `comet_token` value in the payload)
* **Fingerprint**

### Why these fields matter

* **Email, phone, name and IP** help with identity matching and conversion quality.
* **Comet Token and Fingerprint** connect the purchase back to the exact visitor tracked by the Cometly pixel.
* **Amount** powers accurate revenue attribution and ROAS reporting.

### Choose the correct Amount field

When you map the **Amount** field, select:

```text theme={null}
current_total_price
```

`current_total_price` represents the final amount the customer paid for the order. It includes all components of the purchase, such as:

* Product prices
* Discounts
* Shipping
* Taxes
* Additional fees or duties

Because of this, it reflects the true revenue value of the transaction, which is what Cometly uses for reporting and attribution.

> [!WARNING]
>
> If `comet_token` and `fingerprint` are missing from the payload, it usually means the Cometly pixel was not installed when the order was placed, or the customer completed checkout on a path where the pixel was not firing.

## Step 5: Test the webhook end to end

Do a real test so you know Shopify is sending data and Cometly is receiving it.

1. Open a new browser window.

2. Visit your Shopify store and browse at least 1 to 2 pages.

3. Complete a test purchase (use a real payment method or a test method based on your store setup).

4. Confirm in Shopify that the order status reflects **paid**.

5. In Cometly, go to **Events Manager** > **Events Log**, set **Source** to **Server**, and:

   * Confirm the Purchase event arrived
   * Confirm the order has a `comet_token`, `fingerprint` and `ip`, and that the amount is populated

> [!TIP]
>
> If the event arrives but attribution looks wrong, it is almost always a missing `comet_token`, a missing `fingerprint`, or a value mapping issue.

## Step 6: Choose Shopify Meta CAPI or Cometly Meta CAPI

A Conversion API (CAPI) sends your conversions to an ad platform from the server instead of the browser. You can use either Shopify's native Meta Conversion API integration or Cometly's Meta Conversion API, but you can only run one Meta CAPI connection for the same pixel setup.

See the [Meta Conversion API guide](https://docs.cometly.com/guides/conversion-api/meta.md).

* Use **Cometly Meta CAPI** if you want server-side events aligned to Cometly attribution, plus deeper visibility and control over mapping, match signals and event definitions.
* Use **Shopify's native Meta CAPI** if you want a basic Shopify-managed connection and you do not need Cometly controlling the event stream.

> [!WARNING]
>
> Do not run both Conversion APIs at the same time. Double sending can inflate conversions and create reporting discrepancies. You can only have one Conversion API configured for Meta or you will have duplicate events.

## Step 7: Set up the Google Conversion API (recommended if you want server-side Google tracking)

For Google, you can create separate conversion actions specifically for events coming from Cometly.

See [how to configure the Google Conversion API](https://docs.cometly.com/guides/conversion-api/google.md).

## Check it worked

In Cometly, go to **Events Manager** > **Events Log** and set **Source** to **Server**. Each new paid Shopify order appears there as a **Purchase** event within 60 seconds, with **SUCCESS** in the **Details** column and the amount, `comet_token` and `fingerprint` filled in.

## Common issues and fixes

**`comet_token` is missing in the webhook payload**

* Confirm the Cometly pixel is installed before `</head>` in `theme.liquid`
* Make sure the customer completed the order after the pixel was installed
* Ensure the pixel loads on all storefront pages involved in the checkout flow

**Purchase amount is wrong**

* Make sure you mapped the correct value field (total paid, not subtotal)
* Confirm currency formatting matches what Cometly expects

**Webhook not firing**

* Re-check the Shopify webhook event selection (must be order paid / payment captured)
* Confirm the webhook URL is pasted correctly
* Place a new paid test order and check Shopify webhook delivery logs if available.

## Track Add to Cart and Initiate Checkout events

If you would like to track Add to Cart and Initiate Checkout events for your Shopify store, follow the [Add to Cart and Initiate Checkout guide](https://docs.cometly.com/guides/events/add-to-cart-and-initiate-checkout.md).

## Troubleshooting

### Cometly is not tracking all orders

Cometly is designed to track all your Shopify orders. For example, if you see 10 orders in Shopify for a given day, you should see 10 orders in Cometly, provided that the timezones in your Cometly and Shopify account settings are aligned.

If the numbers do not match, follow these steps:

1. **Check the Events Log in Cometly:** Go to **Events Manager** > **Events Log** and look for any errors.
2. **Common issue, missing email:** One of the most common errors occurs when the "Email" field is not passed through for certain orders. Cometly relies on email addresses to track orders and build customer journeys. If an email is missing, the order cannot be tracked.
3. **Orders created by third-party apps:** If you're using third-party apps that generate orders and pass them into your Shopify store, these apps may not share customer email addresses with Shopify. As a result, Cometly cannot track these orders, and you will see them flagged as errors in the Events Log.

To resolve these issues, ensure that all orders passing through your Shopify store include the required data, particularly customer email addresses.

## Frequently asked questions

### Why are my Shopify sales not showing in Cometly when payment capture is manual?

Cometly records a purchase when Shopify reports the order as paid. If your store's payment capture is set to "Manual" instead of "Automatic", Cometly may not be able to report your sales. Switch the setting to "Automatic" as described in [Shopify automatic payment capture](https://docs.cometly.com/support/troubleshooting/events/shopify-automatic-payment-capture.md).

### How do I stop Shopify orders from being counted twice in Cometly?

Map the Shopify order ID to the Cometly field **Order Id** on the mapping step. Cometly then ignores any repeat of the same event name and Order ID for that customer, for example when a webhook is retried. See [how Order ID works](https://docs.cometly.com/guides/tracking/order-id.md).

### Can I track only first-time purchases from a Shopify subscription store?

Yes. By default, Cometly tracks every purchase as a **Purchase** event. To record initial orders separately, create a second webhook event as described in [Track first-time purchases in Shopify](https://docs.cometly.com/integrations/guides/shopify-first-time-purchases.md).

## Next steps

* [Track Add to Cart and Initiate Checkout events](https://docs.cometly.com/guides/events/add-to-cart-and-initiate-checkout.md)
* [Send purchases to Meta with the Meta Conversion API](https://docs.cometly.com/guides/conversion-api/meta.md)
* [Configure the Google Conversion API](https://docs.cometly.com/guides/conversion-api/google.md)
* [Track first-time purchases in Shopify](https://docs.cometly.com/integrations/guides/shopify-first-time-purchases.md)
* [Learn how webhook mapping, filters and activation work](https://docs.cometly.com/integrations/webhooks.md)

Still have questions or need a hand? We're happy to help. Reach our team at [support@cometly.com](mailto:support@cometly.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.