> ## Documentation Index
> Fetch the complete documentation index at: https://docs.postmetric.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Track custom goals
> Track custom user actions (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:
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
## Reliable tracking (recommended)
Add this script to your HTML `` to guarantee events are captured even when triggered before the main script loads:
```html theme={null}
```
## Method 1: JavaScript
### Simple goal (by name)
```javascript theme={null}
window?.postmetric("signup");
window?.postmetric("newsletter_subscribe");
```
### Goal with custom parameters
```javascript theme={null}
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
```javascript theme={null}
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
```html theme={null}
```
### With custom parameters
```html theme={null}
```
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)
```bash theme={null}
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)
```bash theme={null}
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](/api-reference/goal) for details.
## Common goal examples
### Form submission
```javascript theme={null}
document.getElementById("contact-form").addEventListener("submit", function () {
postmetric("form_submit");
});
```
### Button click
```javascript theme={null}
document.getElementById("cta-button").addEventListener("click", function () {
postmetric("cta_click");
});
```
### Video play
```javascript theme={null}
document.getElementById("video").addEventListener("play", function () {
postmetric("video_play");
});
```
### File download
```html theme={null}
Download PDF
```
## 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
Learn how to track multi-step conversion funnels