# Conversion Events

## Supported events

Below is a list of the event methods you can pass to the `chartbeat()` function, followed by a list of [optional parameters](#event-parameters) you can send with each method. You should fire a Chartbeat event from the same category on every page in a single conversion flow. 

### Subscriptions

Track paywall activity and subscription transactions on your site.

<table data-header-hidden data-full-width="true"><thead><tr><th width="251">Event</th><th>Description</th><th></th></tr></thead><tbody><tr><td><strong>Event Name</strong></td><td><strong>Description</strong></td><td><strong>Requirement</strong></td></tr><tr><td><code>trackPaywallShown</code></td><td>A user was shown a paywall</td><td>Required</td></tr><tr><td><code>trackPaywallStart</code></td><td>A user started a subscription process</td><td><em>Optional</em></td></tr><tr><td><code>trackPaywallComplete</code></td><td>A user completed a subscription transaction</td><td>Required</td></tr><tr><td><code>trackPaywallCancel</code></td><td>A user canceled a subscription process</td><td><em>Optional</em></td></tr></tbody></table>

### Registrations

Track registration activity (i.e. users creating an account) on your site.

<table data-header-hidden data-full-width="true"><thead><tr><th width="298">Event</th><th>Description</th><th></th></tr></thead><tbody><tr><td><strong>Event Name</strong></td><td><strong>Description</strong></td><td><strong>Requirement</strong></td></tr><tr><td><code>trackRegistrationShown</code></td><td>A user viewed a registration screen</td><td>Required</td></tr><tr><td><code>trackRegistrationStart</code></td><td>A user started the registration process</td><td><em>Optional</em></td></tr><tr><td><code>trackRegistrationComplete</code></td><td>A user completed the registration process</td><td>Required</td></tr><tr><td><code>trackRegistrationCancel</code></td><td>A user canceled the registration process</td><td><em>Optional</em></td></tr></tbody></table>

### **Newsletter Signups**

Track newsletter signup activity on your site.

<table data-header-hidden data-full-width="true"><thead><tr><th width="336">Event</th><th>Description</th><th></th></tr></thead><tbody><tr><td><strong>Event Name</strong></td><td><strong>Description</strong></td><td><strong>Requirement</strong></td></tr><tr><td><code>trackNewsletterSignupShown</code></td><td>A user was shown a newsletter signup option</td><td>Required</td></tr><tr><td><code>trackNewsletterSignupStart</code></td><td>A user started a signup process</td><td><em>Optional</em></td></tr><tr><td><code>trackNewsletterSignupComplete</code></td><td>A user completed a signup process</td><td>Required</td></tr><tr><td><code>trackNewsletterSignupCancel</code></td><td>A user canceled a signup process</td><td><em>Optional</em></td></tr></tbody></table>

### Unsubscribes

Track unsubscribe activity on your site.

<table data-header-hidden data-full-width="true"><thead><tr><th width="298.5">Event</th><th>Description</th><th></th></tr></thead><tbody><tr><td><strong>Event Name</strong></td><td><strong>Description</strong></td><td><strong>Requirement</strong></td></tr><tr><td><code>trackUnsubscribeShown</code></td><td>A user visited an unsubscribe page</td><td><em>Optional</em></td></tr><tr><td><code>trackUnsubscribeStart</code></td><td>A user started an unsubscribe flow</td><td><em>Optional</em></td></tr><tr><td><code>trackUnsubscribeComplete</code></td><td>A user unsubscribed</td><td>Required</td></tr><tr><td><code>trackUnsubscribeCancel</code></td><td>A user dismissed an unsubscribe flow</td><td><em>Optional</em></td></tr></tbody></table>

### Offers

Track offer activity on your site.

<table data-header-hidden data-full-width="true"><thead><tr><th width="241.5">Event</th><th>Description</th><th></th></tr></thead><tbody><tr><td><strong>Event Name</strong></td><td><strong>Description</strong></td><td><strong>Requirement</strong></td></tr><tr><td><code>trackOfferShown</code></td><td>A user was shown an offer</td><td><em>Optional</em></td></tr><tr><td><code>trackOfferStart</code></td><td>A user started an offer</td><td><em>Optional</em></td></tr><tr><td><code>trackOfferComplete</code></td><td>A user completed an offer</td><td>Required</td></tr><tr><td><code>trackOfferCancel</code></td><td>A user dismissed an offer</td><td><em>Optional</em></td></tr></tbody></table>

### Surveys

Track survey activity on your site.

<table data-header-hidden data-full-width="true"><thead><tr><th width="246.33333333333331">Event</th><th>Description</th><th></th></tr></thead><tbody><tr><td><strong>Event Name</strong></td><td><strong>Description</strong></td><td><strong>Requirement</strong></td></tr><tr><td><code>trackSurveyShown</code></td><td>A user was shown a survey</td><td><em>Optional</em></td></tr><tr><td><code>trackSurveyStart</code></td><td>A user started a survey</td><td><em>Optional</em></td></tr><tr><td><code>trackSurveyComplete</code></td><td>A user completed a survey</td><td>Required</td></tr><tr><td><code>trackSurveyCancel</code></td><td>A user dropped off a survey</td><td><em>Optional</em></td></tr></tbody></table>

### Account Creations

Track user profile activity (e.g. filling out text fields) on your site.

<table data-header-hidden data-full-width="true"><thead><tr><th width="287.3333333333333">Event</th><th width="321">Description</th><th></th></tr></thead><tbody><tr><td><strong>Event Name</strong></td><td><strong>Description</strong></td><td><strong>Requirement</strong></td></tr><tr><td><code>trackUserProfileShown</code></td><td>A user viewed their profile</td><td><em>Optional</em></td></tr><tr><td><code>trackUserProfileStart</code></td><td>A user started editing their profile</td><td><em>Optional</em></td></tr><tr><td><code>trackUserProfileComplete</code></td><td>A user completed editing to their profile</td><td>Required</td></tr><tr><td><code>trackUserProfileCancel</code></td><td>A user exited profile-editing mode</td><td><em>Optional</em></td></tr></tbody></table>

### Downloads

Track download activity (e.g. pdf case studies, apps) on your site.

<table data-header-hidden data-full-width="true"><thead><tr><th width="258.3333333333333">Event</th><th width="297">Description</th><th></th></tr></thead><tbody><tr><td><strong>Event Name</strong></td><td><strong>Description</strong></td><td><strong>Requirement</strong></td></tr><tr><td><code>trackDownloadStart</code></td><td>A user started downloading data</td><td><em>Optional</em></td></tr><tr><td><code>trackDownloadComplete</code></td><td>A download has completed</td><td>Required</td></tr><tr><td><code>trackDownloadCancel</code></td><td>A download was canceled </td><td><em>Optional</em></td></tr></tbody></table>

### Donations

Track donation activity on your site.

<table data-header-hidden data-full-width="true"><thead><tr><th width="264.3333333333333">Event</th><th>Description</th><th></th></tr></thead><tbody><tr><td><strong>Event Name</strong></td><td><strong>Description</strong></td><td><strong>Requirement</strong></td></tr><tr><td><code>trackDonationShown</code></td><td>An option to donate was shown</td><td><em>Optional</em></td></tr><tr><td><code>trackDonationStart</code></td><td>A user started the donation process</td><td><em>Optional</em></td></tr><tr><td><code>trackDonationComplete</code></td><td>A user completed the donation process</td><td>Required</td></tr><tr><td><code>trackDonationCancel</code></td><td>A user canceled the donation process</td><td><em>Optional</em></td></tr></tbody></table>

### Payments

Track payment activity on your site (other than payment for a subscription).

<table data-header-hidden data-full-width="true"><thead><tr><th width="248.33333333333331">Event</th><th width="325">Description</th><th></th></tr></thead><tbody><tr><td><strong>Event Name</strong></td><td><strong>Description</strong></td><td><strong>Requirement</strong></td></tr><tr><td><code>trackPaymentStart</code></td><td>A user started a payment process</td><td><em>Optional</em></td></tr><tr><td><code>trackPaymentComplete</code></td><td>A user completed a payment process</td><td>Required</td></tr><tr><td><code>trackPaymentCancel</code></td><td>A user canceled a payment process</td><td><em>Optional</em></td></tr></tbody></table>

### Searches

Track completed search queries on your site.

<table data-header-hidden data-full-width="true"><thead><tr><th>Event</th><th>Description</th><th></th></tr></thead><tbody><tr><td><strong>Event Name</strong></td><td><strong>Description</strong></td><td><strong>Requirement</strong></td></tr><tr><td><code>trackSearchComplete</code></td><td>A user performed a search</td><td>Required</td></tr></tbody></table>

### Saves

Track save activity (e.g. a user added an item to their "Favorites" collection) on your site.

<table data-header-hidden data-full-width="true"><thead><tr><th>Event</th><th>Description</th><th>Text</th></tr></thead><tbody><tr><td><strong>Event Name</strong></td><td><strong>Description</strong></td><td><strong>Requirement</strong></td></tr><tr><td><code>trackSaveComplete</code></td><td>A user saved an item for future retrieval</td><td>Required</td></tr></tbody></table>

## Call t**he `chartbeat()` function**

Once you've [added the subscriptions.js snippet](broken://pages/sgUstYHXhbBSAwR63LCj) to your webpages, call the global `chartbeat()` function to track subscription events — with or without [optional parameters](#event-parameters).&#x20;

```javascript
chartbeat('event_name', { // CHANGE THIS TO THE SUPPORTED EVENT YOU WANT TO TRACK
    pathOverride, // optional
    eventLabel, // optional
    eventValue, // optional
} )
```

Track activity related to offers on your site.

## Event parameters

There are 3 *optional* parameters you can send with each event:

<table data-header-hidden data-full-width="false"><thead><tr><th>Optional Parameter</th><th width="144">Type</th><th width="112">Default</th><th>Description</th></tr></thead><tbody><tr><td>Optional Parameter</td><td>Type</td><td>Default</td><td>Description</td></tr><tr><td><code>pathOverride</code></td><td>string</td><td>null</td><td>Set a path different from the one sent by your standard configuration <strong>(not recommended)</strong></td></tr><tr><td><code>eventLabel</code></td><td>string</td><td>null</td><td>Set a label (e.g. <code>monthly</code> or <code>annual</code> subscription package)</td></tr><tr><td><code>eventValue</code></td><td>number</td><td>null</td><td>Set a value (e.g. the price of the subscription package)</td></tr></tbody></table>

{% hint style="warning" %}
Optional event parameters are not currently surfaced in any Chartbeat product.
{% endhint %}

## Examples

Here is a basic example that you would add to your paywall's "Complete" event handler:

```
// Add to your Paywall Complete event handler

chartbeat('trackPaywallComplete');
```

### Google Analytics Tag Manager

<figure><img src="/files/7RD5CFxYZVPO4YX4zjHU" alt=""><figcaption><p>An example of an implementation using a new Tag in Google Analytics Tag Manager linked to an existing Trigger</p></figcaption></figure>

### Piano Composer

Below is an example from [Piano Composer](https://piano.io/product/composer/):

```javascript
tp.push(["addHandler", "checkoutComplete", function(conversionData){
    chartbeat('trackPaywallComplete');
}]);
```

## Next Steps

Review our **integration QA instructions** article for best practices.&#x20;


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.chartbeat.com/cbp/feature-integrations/conversion/conversion-events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.