Events in API Payloads

This guide explains how to include events within other API payloads, such as the People API endpoints. While events can be tracked directly through the Events API, you can also include them as part of other API requests.

Overview

When working with APIs that support event tracking (like the People API), you can include an array of events in your payload. Each event in the array follows the same validation rules and structure as if it were sent directly to the Events API endpoints, with the key differences being that:

• The event object must have an eventName field.
• The event object does not require the email, referenceId, or source fields, as these are provided in the parent request.
• The event object will accept the silent and test fields, which are used to control the event's behavior.

{
  "email": "[email protected]",
  "source": "woocommerce",
  "events": [
    {
      "eventName": "product_viewed",
      "id": "prod_123",
      "name": "Awesome T-Shirt"
    },
    {
      "eventName": "cart_created",
      "id": "cart_456",
      "products": [/* ... */]
    },
    {
      "eventName": "customer_created",
      "id": "cust_789",
      "first_name": "John",
      "last_name": "Doe"
    },
    {
      "eventName": "custom_event",
      "value": 99.99
    }
  ]
}

Defined Events

Lindris has several defined event types that follow a specific naming convention. These event types have reserved namespaces and require specific actions:

Product Events

• Must use one of these actions:
  • product_viewed
  • product_created
  • product_updated
  • product_deleted

Details

Cart Events

• Must use one of these actions:
  • cart_created
  • cart_updated
  • cart_abandoned

Details

Order Events

• Must use one of these actions:
  • order_created
  • order_completed
  • order_updated
  • order_deleted

Details

Customer Events

• Must use one of these actions:
  • customer_created
  • customer_updated
  • customer_deleted

Customer events can include an optional is_contact: true flag to automatically sync customer data to Lindris contacts. When this flag is set, relevant customer fields will be mapped to contact fields without requiring separate API calls to the People API.

Details

User Events

• Must use one of these actions:
  • user_created
  • user_updated
  • user_deleted

User events track changes to user accounts and require specific fields like id. Optional fields include user_name, user_email, user_first_name, user_last_name, user_role, user_url, and various timestamp fields (created_at, modified_at, deleted_at).

Details

Subscription Events

• Must use one of these actions:
  • subscription_created
  • subscription_updated
  • subscription_deleted
  • subscription_renewed
  • subscription_cancelled
  • subscription_expired
  • subscription_renewal_failed

Subscription events track the lifecycle of subscriptions and require an id field. They can optionally include a url field for linking to the subscription details.

Details

WARNING

Using an unsupported action with a defined event namespace (e.g., product_destroyed) will result in a validation error.

Custom Events

Any event name that doesn't use a defined namespace (product_, cart_, order_, customer_) is treated as a custom event. These events have more flexible validation rules and can use any name format.

Details

Validation Rules

When including events in your payload:

1. The events field must be an array
2. Each event must have an eventName field
3. Defined event types must use supported actions
4. Each event type follows its specific validation rules (see Events API)
5. Events are validated individually, with errors reported by index
6. Some fields are mutually exclusive (e.g., variant_id and variants array)

Example Error Responses

Here are some common validation error scenarios:

Invalid Event Action and Field Conflicts

{
  "message": "Event `product_viewed` at index 0: The variant_id field cannot be used when variants array is present. (and 3 more errors)",
  "errors": {
    "events": [
      "Event `product_viewed` at index 0: The variant_id field cannot be used when variants array is present.",
      "Event `product_viewed` at index 0: The variants array cannot be used when variant_id is present.",
      "Events prefixed with `product_` are reserved for defined events",
      "Event `product_destroyed` at index 1: Invalid action `destroyed` for `product` event."
    ]
  },
  "status_code": 422
}

Missing Required Fields

{
	"message": "The event at index 0 must have an eventName.",
	"errors": {
		"events": [
			"The event at index 0 must have an eventName."
		]
	},
	"status_code": 422
}

{
	"message": "Event `product_viewed` at index 0: The id field is required.",
	"errors": {
		"events": [
			"Event `product_viewed` at index 0: The id field is required."
		]
	},
	"status_code": 422
}

{
	"message": "Event `customer_created` at index 2: The id field is required.",
	"errors": {
		"events": [
			"Event `customer_created` at index 2: The id field is required."
		]
	},
	"status_code": 422
}

Invalid Event Structure

{
	"message": "The event at index eventName must be an array. (and 1 more error)",
	"errors": {
		"events": [
			"The event at index eventName must be an array.",
			"The event at index value must be an array."
		]
	},
	"status_code": 422
}

TIP

When submitting events in a payload:

• Each event is validated independently
• Errors will reference the event's index in the array
• Multiple validation errors may be returned at once
• Check both the top-level message and the errors object for details

Event Processing

Events included in API payloads are processed the same way as if they were sent directly to the Events API. This means:

• Each event is validated individually
• The same workflow automations are triggered (unless silent: true)
• The same tracking and analytics are recorded
• The event uuid is set on the person object if it is not already set

For detailed information about event properties and requirements, refer to the Events API documentation.