Skip to main content
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:
  1. Go to your website settings in the dashboard
  2. Click “Goals” in the sidebar
  3. Click “Create Goal”
  4. Enter:
    • Name - A descriptive name (e.g., “Newsletter Signup”)
    • Event - The event identifier (e.g., “newsletter_signup”)
    • Description - Optional description
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

  1. Use descriptive event names - Use clear, consistent naming (e.g. newsletter_signup, not ns)
  2. Track meaningful actions - Focus on actions that matter to your business
  3. Include values when relevant - Add numeric values for revenue-related goals
  4. 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