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!);
- 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.
- Step 2 — Query events and metrics.
MetricsApi.getMetrics() lists event types;
EventsApi.getEvents({ sort: '-datetime', filter: 'equals(metric_id,"...")' }) reads recent events.
- 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.
- 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.
- 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
