Skip to main content

​
Overview

Custom events allow you to track specific user actions beyond pageviews, such as button clicks, form submissions, file downloads, and purchases. Custom events are sent to the same Event Ingestion endpoint as pageviews.

​
Sending Custom Events

Custom events use the same /api/event endpoint as pageviews, but with a custom event name. 
POST /api/event

​
Event Names

​
n
string
required
Custom event name (also accepts name field)Requirements:
  • Maximum length: 120 characters
  • Cannot be empty or whitespace
  • Cannot be engagement (reserved for internal use)
Common examples:
  • Signup
  • Purchase
  • Download
  • Outbound Link: Click
  • File Download
  • Form: Submission
  • 404

​
Custom Properties

Attach additional metadata to your custom events using custom properties (props).
​
p
object
Custom properties object (also accepts props, m, or meta fields)Constraints:
  • Maximum 30 properties per event
  • Property keys: maximum 300 bytes
  • Property values: maximum 2000 bytes
  • Both keys and values must be strings
Example:
{
  "plan": "premium",
  "method": "stripe",
  "amount": "99"
}

​
System Events

Plausible provides several built-in system events that can be automatically tracked: Event name: Outbound Link: Click Tracks clicks on external links leaving your domain.

​
File Downloads

Event name: File Download Tracks downloads of common file types (PDF, ZIP, etc.).

​
Form Submissions

Event name: Form: Submission Tracks form submission events.

​
404 Pages

Event name: 404 Tracks page not found errors. Event names can be integers or strings.

​
Examples

​
Basic Custom Event

curl -X POST https://plausible.io/api/event \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0" \
  -d '{
    "n": "Signup",
    "u": "https://example.com/signup/success",
    "d": "example.com"
  }'

​
Custom Event with Properties

curl -X POST https://plausible.io/api/event \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0" \
  -d '{
    "n": "Purchase",
    "u": "https://example.com/checkout/success",
    "d": "example.com",
    "p": {
      "product": "Premium Plan",
      "variant": "annual",
      "currency": "USD"
    }
  }'

​
Button Click Tracking

document.getElementById('cta-button').addEventListener('click', () => {
  plausible('CTA Click', {
    props: {
      button: 'Get Started',
      location: 'hero'
    }
  });
});

​
File Download Tracking

document.querySelectorAll('a[href$=".pdf"]').forEach(link => {
  link.addEventListener('click', (e) => {
    plausible('File Download', {
      props: {
        filename: e.target.href.split('/').pop(),
        type: 'pdf'
      }
    });
  });
});

​
Event Processing

When a custom event is received:
  1. Validation - Event name and properties are validated
  2. User Identification - User ID is generated from IP, user agent, and domain
  3. Geolocation - Country, region, and city are detected from IP
  4. Device Detection - Browser, OS, and screen size are parsed from user agent
  5. Source Attribution - Referrer and UTM parameters are processed
  6. Shield Rules - Event is checked against IP, country, page, and hostname filters
  7. Session Management - Event is associated with or creates a new session
  8. Buffering - Event is buffered and written to ClickHouse

​
Custom Event Goals

To track conversions for custom events, you need to create a goal in your Plausible dashboard or via the Goals API. See the Create Goal endpoint for details on setting up custom event goals.

​
Best Practices

  1. Use descriptive event names - Make event names clear and specific (Signup instead of click)
  2. Keep property keys short - Use concise keys to save space (plan instead of subscription_plan_type)
  3. Use consistent naming - Maintain a naming convention across your events
  4. Limit property count - Only track properties you’ll actually use for analysis
  5. String values only - Convert numbers and booleans to strings for properties
  6. Test events first - Verify events appear in your dashboard before deploying

Build docs developers (and LLMs) love

Get started for freeTalk to us