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

# Track conversion events

> Track purchases, sign-ups, and other actions that result from search to measure search effectiveness.

Conversion tracking records when a user completes a desired action after finding something through search. While [click events](https://www.meilisearch.com/docs/capabilities/analytics/how_to/track_click_events.md) tell you which results users interact with, conversion events tell you which results deliver real business value.

## Clicks vs. conversions

| Event type | What it measures | Example |
| :- | :- | :- |
| Click | User viewed or opened a search result | User clicks on a product in search results |
| Conversion | User completed a meaningful action | User adds that product to their cart or completes a purchase |

Click events measure engagement with search results. Conversion events measure whether search actually drives outcomes. Together, they give you a complete picture of search quality.

## Define your conversions

Before implementing tracking, decide what actions count as conversions for your use case:

| Application type | Typical conversion |
| :- | :- |
| E-commerce | Adding to cart, completing a purchase |
| Content platform | Reading an article, subscribing |
| Documentation site | Copying a code sample, following a tutorial |
| Job board | Applying to a job listing |
| SaaS product | Starting a free trial, upgrading a plan |

Pick the action that best represents a successful search outcome for your business.

## Send a conversion event

When a user completes a conversion action, send a `conversion` event to the `POST /events` endpoint:

```bash cURL theme={null}
curl \
  -X POST 'https://PROJECT_URL/events' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer DEFAULT_SEARCH_API_KEY' \
  --data-binary '{
    "eventType": "conversion",
    "eventName": "Product Added To Cart",
    "indexUid": "products",
    "userId": "SEARCH_USER_ID",
    "objectId": "0",
    "objectName": "DOCUMENT_DESCRIPTION",
    "position": 0
  }'
```

### Required and recommended fields

| Field | Required | Description |
| :- | :- | :- |
| `eventType` | Yes | Must be `"conversion"` |
| `eventName` | Yes | A descriptive label, such as `"Product Added To Cart"` |
| `indexUid` | Yes | The index containing the converted document |
| `userId` | Yes | An arbitrary string identifying the user |
| `objectId` | Recommended | The [primary key](https://www.meilisearch.com/docs/resources/internals/primary_key.md) of the converted document |
| `queryUid` | Recommended | The UID of the original search query |
| `objectName` | Optional | A human-readable description of the document |

The `queryUid` links the conversion back to the original search request. You can find it in the [`metadata` field present in search query responses](https://www.meilisearch.com/docs/reference/api/headers#search-metadata).

> [!NOTE]
>
> It is not possible to associate multiple `conversion` events with the same query. If a user converts on the same query twice, only the first event is recorded.

## When to fire conversion events

Conversion events should be sent at the moment the user completes the action, not when they first view the result. In a typical e-commerce flow:

1. User searches for "wireless headphones" (search request)
2. User clicks on a product (click event)
3. User reads the product page (no event)
4. User adds the product to their cart (conversion event)

```javascript theme={null}
async function handleAddToCart(product, queryUid) {
  // Add the product to the cart in your application
  await addToCart(product.id);

  // Send the conversion event to Meilisearch
  await fetch('https://PROJECT_URL/events', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer DEFAULT_SEARCH_API_KEY',
    },
    body: JSON.stringify({
      eventType: 'conversion',
      eventName: 'Product Added To Cart',
      indexUid: 'products',
      userId: getCurrentUserId(),
      queryUid: queryUid,
      objectId: product.id,
      objectName: product.title,
    }),
  });
}
```

> [!TIP]
>
> Store the `queryUid` when the user performs a search, then pass it along as the user navigates through your application. This ensures you can still associate a conversion with the original query even if the conversion happens on a different page.

## Best practices

* **Track the most meaningful action.** If you track too many conversion types, the conversion rate metric becomes less useful. Focus on the action that best represents search success.
* **Preserve the `queryUid` across pages.** Store it in session storage or pass it as a URL parameter so you can associate conversions with the search that led to them.
* **Use consistent user IDs.** The same user should have the same `userId` across all searches and events.
* **Do not send duplicate conversions.** Only one conversion event per query is recorded, so avoid sending the same event multiple times.

## Next steps

> [card] [Getting started with analytics](https://www.meilisearch.com/docs/capabilities/analytics/getting_started.md)
>
> Set up click and conversion tracking from scratch

> [card] [Events endpoint reference](https://www.meilisearch.com/docs/capabilities/analytics/advanced/events_endpoint.md)
>
> Full reference for the `/events` endpoint fields and behavior

> [card] [Track click events](https://www.meilisearch.com/docs/capabilities/analytics/how_to/track_click_events.md)
>
> Record which search results users click on

> [card] [Bind events to a user](https://www.meilisearch.com/docs/capabilities/analytics/how_to/bind_events_to_user.md)
>
> Learn how to associate analytics events with specific users


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