Klaviyo Core Workflow B -- Events, Segments & Campaigns

Overview

Secondary workflow: track customer events, query segments, create/send campaigns, and trigger metric-based flows via the klaviyo-api SDK. This page summarizes the five steps and their skeletons; the full copy-ready code lives in references/implementation.md and worked scenarios in references/examples.md.

Prerequisites

• Completed klaviyo-core-workflow-a (profiles/lists set up)
• API key scopes: events:write, segments:read, campaigns:read, campaigns:write, flows:read
• klaviyo-api installed and KLAVIYO_PRIVATE_KEY set in the environment

Instructions

Open one session, then use the API class each step needs. Full parameter shapes for every step are in references/implementation.md.

import { ApiKeySession, EventsApi } from 'klaviyo-api';
const session = new ApiKeySession(process.env.KLAVIYO_PRIVATE_KEY!);

1. Step 1 — Track server-side events. new EventsApi(session).createEvent(...). Include metric.data.attributes.name (auto-creates the metric), a profile, a value for revenue attribution, and a uniqueId for deduplication. Custom metrics trigger listening flows.
2. Step 2 — Query events and metrics. MetricsApi.getMetrics() lists event types; EventsApi.getEvents({ sort: '-datetime', filter: 'equals(metric_id,"...")' }) reads recent events.
3. Step 3 — Work with segments. SegmentsApi.getSegments() lists them, getSegmentProfiles() reads members, and getSegment({ additionalFieldsSegment: ['profile_count'] }) returns the size — check it before a send.
4. Step 4 — Create an email campaign. Four ordered calls: create a template, create the campaign (with audiences.included/excluded), assign the template to the campaign message, then create the campaign-send-job. Sending before the template is assigned returns a 400.
5. Step 5 — Query flows (read-only). FlowsApi.getFlows() lists flows; getFlowFlowActions({ id }) returns each flow's steps and their status.

Output

• Event tracking returns an HTTP 202 Accepted acknowledgement (Klaviyo queues events asynchronously); the event appears in the profile's activity feed and fires any flow listening on that metric.
• Metric/segment/flow queries return a body.data array of records with id and attributes (name, status, profileCount, etc.).
• Campaign creation yields a campaign id; the send job queues the campaign, and Klaviyo reports delivery back in the app's campaign analytics.

Common Event Names for Flow Triggers

Event name	Typical trigger	Flow type
Placed Order	Purchase completed	Post-purchase / cross-sell
Started Checkout	Cart created	Abandoned cart
Viewed Product	Product page visit	Browse abandonment
Ordered Product	Per-item tracking	Product review request
Fulfilled Order	Shipment sent	Shipping confirmation
Cancelled Order	Order cancelled	Win-back
Subscribed to List	Email/SMS signup	Welcome series
Custom Event	Any API event	Custom automation

Error Handling

Error	Status	Cause	Solution
Invalid metric name	400	Empty or null metric	Always include metric.data.attributes.name
Segment not found	404	Wrong segment ID	List segments with getSegments()
Campaign send failed	400	Missing template/audience	Assign template and set audience first
Duplicate event	N/A	Same uniqueId	Deduplication built-in; safe to retry

Examples

Concrete, runnable scenarios are collected in references/examples.md:

• Fire an abandoned-cart signal — track a Started Checkout event for a flow to pick up.
• Size a segment before sending — read profileCount and refuse to send to an empty audience.
• Create and send a campaign to a segment — the ordered template → campaign → assign → send-job chain.

A minimal event track:

import { EventsApi, EventEnum, ProfileEnum } from 'klaviyo-api';
const eventsApi = new EventsApi(session);

await eventsApi.createEvent({
  data: {
    type: EventEnum.Event,
    attributes: {
      metric: { data: { type: 'metric', attributes: { name: 'Placed Order' } } },
      profile: { data: { type: ProfileEnum.Profile, attributes: { email: 'customer@example.com' } } },
      value: 99.97,
      time: new Date().toISOString(),
      uniqueId: 'ORD-12345',
    },
  },
});

Resources

• Full implementation walkthrough — copy-ready code for all five steps
• Worked examples — end-to-end scenarios
• Events API
• Segments API
• Campaigns API
• Flows API
• Metrics API
• For common errors, see the klaviyo-common-errors skill.