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

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.