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 KLAVIYOPRIVATEKEY 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.

1. Step 2 — Query events and metrics. MetricsApi.getMetrics() lists event types;

EventsApi.getEvents({ sort: '-datetime', filter: 'equals(metric_id,"...")' }) reads recent events.

1. 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.

1. 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.

1. 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

Error Handling

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.