Track custom goals

Track any user action as a conversion goal to measure what matters to your business.

What are goals?

Goals are custom events that you want to track, such as:

Button clicks
Form submissions
Video plays
File downloads
Newsletter signups
Product purchases
Any custom user action

Create a goal

Goals are auto-created when you track them. You can also predefine goals in the dashboard:

Go to your website settings in the dashboard
Click “Goals” in the sidebar
Click “Create Goal”
Enter:
- Name - A descriptive name (e.g., “Newsletter Signup”)
- Event - The event identifier (e.g., “newsletter_signup”)
- Description - Optional description

Reliable tracking (recommended)

Add this script to your HTML <head> to guarantee events are captured even when triggered before the main script loads:

<script id="postmetric-queue">
  window.postmetric = window.postmetric || function() {
    window.postmetric.q = window.postmetric.q || [];
    window.postmetric.q.push(arguments);
  };
</script>

Method 1: JavaScript

Simple goal (by name)

window?.postmetric("signup");
window?.postmetric("newsletter_subscribe");

Goal with custom parameters

window?.postmetric("initiate_checkout", {
  name: "Elon Musk",
  email: "elon@x.com",
  product_id: "prod_123",
  price: "49",
  currency: "USD",
});

Rules for goal names:

Use lowercase letters
Numbers, underscores (_), and hyphens (-) are allowed
Maximum 64 characters

Rules for custom parameters:

Property names: lowercase letters, numbers, underscores (_), and hyphens (-) only. Max 64 characters.
Property values: any string, max 255 characters.
Maximum 10 custom parameters per event.

Goal with value

window?.postmetric("purchase", { value: 99.99 });

Method 2: HTML data attributes

Track goals automatically when users click elements with the data-postmetric-goal attribute.

Simple button

<button data-postmetric-goal="initiate_checkout">Buy Now</button>

With custom parameters

<button
  data-postmetric-goal="initiate_checkout"
  data-postmetric-goal-price="49"
  data-postmetric-goal-currency="USD"
  data-postmetric-goal-plan-type="pro"
>
  Subscribe to Pro Plan
</button>

Parameter names are converted from kebab-case to snake_case (e.g. data-postmetric-goal-product-id → product_id).

Method 3: Server-side API

For best reliability (avoids ad blockers), track goals from your backend:

Using the v1 API (requires API key)

curl -X POST https://your-domain.com/api/v1/goal \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "newsletter_signup",
    "value": 0,
    "visitorId": "visitor_123",
    "sessionId": "session_456",
    "path": "/pricing",
    "custom_param": "value"
  }'

Using the tracking endpoint (uses cookies)

curl -X POST "https://your-domain.com/api/goals/track?site=YOUR_TRACKING_CODE" \
  -H "Content-Type: application/json" \
  -H "Cookie: _pm_vid=visitor_id; _pm_sid=session_id" \
  -d '{
    "event": "newsletter_signup",
    "value": 0,
    "path": "/thank-you"
  }'

See our Goal API documentation for details.

Common goal examples

Form submission

document.getElementById("contact-form").addEventListener("submit", function () {
  postmetric("form_submit");
});

Button click

document.getElementById("cta-button").addEventListener("click", function () {
  postmetric("cta_click");
});

Video play

document.getElementById("video").addEventListener("play", function () {
  postmetric("video_play");
});

File download

<a href="/download.pdf" data-postmetric-goal="pdf_download">
  Download PDF
</a>

Test your setup

Visit /test-goals on your PostMetric instance to verify goal tracking works. Click the buttons to fire events and check your dashboard analytics.

Best practices

Use descriptive event names - Use clear, consistent naming (e.g. newsletter_signup, not ns)
Track meaningful actions - Focus on actions that matter to your business
Include values when relevant - Add numeric values for revenue-related goals
Prefer server-side for critical events - Newsletter signups and purchases are more reliable when tracked from the backend

Next steps

Track conversion funnels

Learn how to track multi-step conversion funnels

Get started

Installation guides

Revenue attribution

Proxy guides

Advanced features

What are goals?

Create a goal

Reliable tracking (recommended)

Method 1: JavaScript

Simple goal (by name)

Goal with custom parameters

Goal with value

Method 2: HTML data attributes

Simple button

With custom parameters

Method 3: Server-side API

Using the v1 API (requires API key)

Using the tracking endpoint (uses cookies)

Common goal examples

Form submission

Button click

Video play

File download

Test your setup

Best practices

Next steps

Track conversion funnels

​What are goals?

​Create a goal

​Reliable tracking (recommended)

​Method 1: JavaScript

​Simple goal (by name)

​Goal with custom parameters

​Goal with value

​Method 2: HTML data attributes

​Simple button

​With custom parameters

​Method 3: Server-side API

​Using the v1 API (requires API key)

​Using the tracking endpoint (uses cookies)

​Common goal examples

​Form submission

​Button click

​Video play

​File download

​Test your setup

​Best practices

​Next steps

Track conversion funnels

What are goals?

Create a goal

Reliable tracking (recommended)

Method 1: JavaScript

Simple goal (by name)

Goal with custom parameters

Goal with value

Method 2: HTML data attributes

Simple button

With custom parameters

Method 3: Server-side API

Using the v1 API (requires API key)

Using the tracking endpoint (uses cookies)

Common goal examples

Form submission

Button click

Video play

File download

Test your setup

Best practices

Next steps