> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voucherify.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom events

> Configure, track, and use custom events for segmentation, validation rules, distributions, and loyalty automation

Custom events are actions taken by your customers, such as abandoning a cart, submitting a review, or completing a tutorial. By tracking these behaviors, you can create **dynamic, behavior-driven campaigns** that react to real-time activity instead of relying on static customer attributes.

With custom events, you can:

* Personalize incentives based on customer behavior.
* Run automated distributions.
* Limit redemptions using event-based rules.
* Award loyalty points when specific actions occur.

<Info>
  <Badge color="gray">Developer setup</Badge>

  Custom events require developer work. Events must be sent to Voucherify explicitly using the [Track custom event](/api-reference/events/track-custom-event) API endpoint.
</Info>

## Custom event workflow overview

The Custom event workflow consists of the following main steps:

<Steps>
  <Step title="Enable tracking">
    Configure your application to call the Voucherify API whenever a customer performs a specific action. Coordinate with your development team to identify the exact triggers for these API calls.

    <Info>
      Tracking ensures that customer behavior is captured in real-time to trigger rewards or messages.
    </Info>
  </Step>

  <Step title="Define the event schema">
    Go to **Project settings** > **Event schema** and add the custom event. You can also include optional metadata fields to provide additional context for the custom event.

    <Info>
      Defining a schema is needed for Voucherify to validate and process incoming event data accurately.
    </Info>
  </Step>

  <Step title="Pass event data">
    Send the specific event data from your system to Voucherify using the [Track custom event](/api-reference/events/track-custom-event) API endpoint. Ensure the data payload matches the schema defined in the previous step.
  </Step>

  <Step title="Automate workflows">
    Use the logged events to power various automation features:

    * **Segmentation**: Group customers based on event frequency.
    * **Validation rules**: Restrict promotions based on event metadata.
    * **Distributions**: Trigger emails, SMS or other notifications when an event occurs.
    * **Loyalty**: Set earning rules based on custom customer actions.

    <Check>
      Verify that Voucherify is receiving the data by checking the **Activity log** in the dashboard.
    </Check>
  </Step>
</Steps>

## Define new custom event

<Info>
  <Badge color="gray">Custom event definition permissions</Badge>

  Only users with the **Admin** role and the **Add and modify Custom event schema** and **Delete Custom event schema** permissions can add, edit, and manage custom event schemas.
</Info>

In **Home**, go to **Project settings** > **Event schema** and **Create new event definition**.

<Steps>
  <Step title="Add new schema">
    Enter the event name and add optional or mandatory metadata together with its type.

    [Metadata](/prepare/metadata) properties are key-value pairs that extend the event structure.
  </Step>

  <Step title="Connect to the API">
    Once the event is defined, you can use the [Track custom event API](/api-reference/events/track-custom-event) endpoint to log customer actions. Each logged event is automatically linked to a specific customer profile.
  </Step>
</Steps>

The custom event is now ready to be used with other Voucherify features.

## Related features

You can use custom events with the following features for better incentive optimization.

<AccordionGroup>
  <Accordion title="Custom events in customer segments">
    You can create [dynamic customer segments](/prepare/customer-segment) which group customers according to the occurrence of a chosen custom event.

    You can set criteria for when the event occurred or how many times.

    Then, you can use the customer segment with other features.
  </Accordion>

  <Accordion title="Custom events in validation rules">
    You can use event-based segments and event metadata to limit incentive validation and redemption.

    For example, you can restrict redemptions based on customer behavior by:

    1. Creating a dynamic segment based on a custom event, like customers who submitted at least two reviews.
    2. Adding a validation rule to a campaign that allows redemption only for that segment.

    As a result, you can run incentives that can be redeemed only when customers' behavior meets defined conditions.

    You can also build validation rules directly using **custom event metadata**, for example:

    * Allow redemption only if `review_type = "video"`
    * Block rewards if `device_type = "test"`

    Validation rules using custom event metadata are available in:

    * Distributions
    * Loyalty earning rules

    Read the [Validation rules](/optimize/validation-rules-reference) article to learn more.
  </Accordion>

  <Accordion title="Custom events in automated distributions">
    With [distributions](https://support.voucherify.io/article/19-how-does-the-distribution-manager-work), you can set up automatic messages in response to event-related actions.

    Your message distribution can combine custom events with the following triggers:

    * **Custom event**: Sends a message immediately when a specific event is logged.
    * **Segment entered**: Sends a message when a customer enters an event-based segment.
    * **Segment left**: Sends a message when a customer no longer meets the segment criteria.

    <Tip>
      You can refine distributions further by adding validation rules based on customer metadata or custom event metadata.
    </Tip>
  </Accordion>

  <Accordion title="Custom events with loyalty earning rules">
    Custom events can be used to add loyalty points to customers' loyalty cards.

    This is useful to award points for customer behavior, like leaving a product review.

    Read the [Earning rules](/build/earning-rules) article to learn how to configure an earning rule.
  </Accordion>

  <Accordion title="Custom events in referral campaigns">
    Custom events can be used as a <Tooltip headline="Conversion event" tip="The specific action that triggers a successful referral in Voucherify. Each campaign can only have one primary conversion event: code redemption or custom event." cta="Read referral program overview" href="/build/referral-campaign-overview">conversion event</Tooltip> in a referral campaign. A new customer is successfully referred when they perform a defined action, meaning the custom event occurs.

    Read the [Create referral campaign](/build/create-referral-campaign) article to learn how to create referrals with custom events.
  </Accordion>

  <Accordion title="Customer profile: internal Voucherify events">
    In addition to custom events, Voucherify tracks over 50 internal customer events out of the box, such as successful redemptions or loyalty point assignments. These events can be used for segmentation, validation rules, and automation without additional development.

    To check internal events for a given customer, go to the detailed view of a given customer > **Activity** tab.
  </Accordion>
</AccordionGroup>