{
"openapi": "3.0.2",
"info": {
"title": "Klaviyo API",
"version": "2026-04-15",
"description": "The Klaviyo REST API. Please visit https://developers.klaviyo.com for more details.",
"contact": {
"name": "Klaviyo Developer Experience Team",
"email": "developers@klaviyo.com",
"url": "https://developers.klaviyo.com"
},
"termsOfService": "https://www.klaviyo.com/legal/api-terms",
"license": {
"name": "License",
"url": "https://www.klaviyo.com/legal"
}
},
"servers": [
{
"url": "https://a.klaviyo.com",
"description": "Production"
}
],
"security": [
{
"Klaviyo-API-Key": []
}
],
"paths": {
"/api/event-bulk-create-jobs": {
"post": {
"operationId": "bulk_create_events",
"summary": "Bulk Create Events",
"description": "Create a batch of events for one or more profiles.\n\nNote that this endpoint allows you to create new profiles or update existing profile properties.\n\nAt a minimum, profile and metric objects should include at least one profile identifier (e.g., `id`, `email`, or `phone_number`) and the metric `name`, respectively.\n\nAccepts up to 1,000 events per request. The maximum allowed payload size is 5MB. A single string cannot exceed 100KB.
*Rate limits*:
Burst: `10/s`
Steady: `150/m`\n\n**Scopes:**\n`events:write`\n\n[OpenAPI Spec](https://raw.githubusercontent.com/klaviyo/openapi/main/openapi/stable/apis/bulk_create_events.json)",
"parameters": [
{
"name": "revision",
"in": "header",
"description": "API endpoint revision (format: YYYY-MM-DD[.suffix])",
"required": true,
"schema": {
"type": "string",
"default": "2026-04-15"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/vnd.api+json": {
"schema": {
"$ref": "#/components/schemas/EventsBulkCreateJob"
}
}
}
},
"responses": {
"202": {
"description": "Success"
},
"4XX": {
"$ref": "#/components/responses/ClientError"
},
"5XX": {
"$ref": "#/components/responses/ServerError"
}
},
"tags": [
"Events"
],
"x-klaviyo-operation-aliases": [
"create_event_bulk_create_job"
],
"x-klaviyo-pre-release": "None",
"x-klaviyo-ratelimit": {
"burst": "10/s",
"steady": "150/m"
},
"x-klaviyo-scopes": [
"events:write"
]
}
}
},
"components": {
"responses": {
"ClientError": {
"description": "Client Error",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"code",
"title",
"detail"
],
"properties": {
"id": {
"type": "string"
},
"code": {
"type": "string"
},
"title": {
"type": "string"
},
"detail": {
"type": "string"
},
"source": {
"type": "object",
"properties": {
"pointer": {
"type": "string"
},
"parameter": {
"type": "string"
}
}
}
}
}
}
},
"required": [
"errors"
]
}
}
}
},
"ServerError": {
"description": "Server Error",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"code",
"title",
"detail"
],
"properties": {
"id": {
"type": "string"
},
"code": {
"type": "string"
},
"title": {
"type": "string"
},
"detail": {
"type": "string"
},
"source": {
"type": "object",
"properties": {
"pointer": {
"type": "string"
},
"parameter": {
"type": "string"
}
}
}
}
}
}
},
"required": [
"errors"
]
}
}
}
}
},
"schemas": {
"BaseEventCreateQueryBulkEntryResourceObject": {
"type": "object",
"properties": {
"type": {
"$ref": "#/components/schemas/EventEnum"
},
"attributes": {
"type": "object",
"properties": {
"properties": {
"description": "Properties of this event (must not exceed 400 properties). The size of the event payload must not exceed 5 MB,\nand each string cannot be larger than 100 KB. For a full list of data limits on event payloads,\nsee [Limitations](https://developers.klaviyo.com/en/reference/events_api_overview#limitations).\n\nNote any top-level property that is not an object can be\nused to create segments. The `$extra` property records any\nnon-segmentable values that can be referenced later, e.g., HTML templates are\nuseful on a segment but are not used to create a segment.",
"type": "object",
"example": {
"Brand": "Kids Book",
"ProductID": 1111,
"ProductName": "Winnie the Pooh"
}
},
"time": {
"description": "When this event occurred. By default, the time the request was received will be used.\nThe time is truncated to the second. The time must be after the year 2000 and can only\nbe up to 1 year in the future.",
"type": "string",
"format": "date-time",
"example": "2022-11-08T00:00:00+00:00",
"nullable": true
},
"value": {
"description": "A numeric, monetary value to associate with this event. For example, the dollar amount of a purchase.",
"type": "number",
"example": 9.99,
"nullable": true
},
"value_currency": {
"description": "The ISO 4217 currency code of the value associated with the event.",
"type": "string",
"example": "USD",
"nullable": true
},
"backfill": {
"description": "When true, the event is recorded but does NOT trigger flows. Use this when backfilling\nhistorical events so existing flow definitions do not re-fire on events that already\nfired in the past.",
"type": "boolean",
"default": false,
"nullable": true
},
"metric": {
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/MetricCreateQueryResourceObject"
}
},
"required": [
"data"
]
},
"unique_id": {
"description": "A unique identifier for an event. If a unique_id is repeated for the same profile and metric,\nthe request will fail and no events will be processed. If this field is not\npresent, this field will use the time to the second. Using the default, this limits only one\nevent per profile per second.",
"type": "string",
"nullable": true
}
},
"required": [
"properties",
"metric"
]
}
},
"required": [
"type",
"attributes"
]
},
"EventBulkCreateEnum": {
"type": "string",
"enum": [
"event-bulk-create"
]
},
"EventBulkCreateJobEnum": {
"type": "string",
"enum": [
"event-bulk-create-job"
]
},
"EventEnum": {
"type": "string",
"enum": [
"event"
]
},
"EventsBulkCreateJob": {
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/EventsBulkCreateJobResourceObject"
}
},
"required": [
"data"
]
},
"EventsBulkCreateJobResourceObject": {
"type": "object",
"properties": {
"type": {
"$ref": "#/components/schemas/EventBulkCreateJobEnum"
},
"attributes": {
"type": "object",
"properties": {
"events-bulk-create": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EventsBulkCreateQueryResourceObject"
}
}
},
"required": [
"data"
]
}
},
"required": [
"events-bulk-create"
]
}
},
"required": [
"type",
"attributes"
]
},
"EventsBulkCreateQueryResourceObject": {
"type": "object",
"properties": {
"type": {
"$ref": "#/components/schemas/EventBulkCreateEnum"
},
"attributes": {
"type": "object",
"properties": {
"backfill": {
"description": "When true, the event is recorded but does NOT trigger flows. Use this when backfilling\nhistorical events so existing flow definitions do not re-fire on events that already\nfired in the past.",
"type": "boolean",
"default": false,
"nullable": true
},
"profile": {
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/OnsiteProfileCreateQueryResourceObject"
}
},
"required": [
"data"
]
},
"events": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BaseEventCreateQueryBulkEntryResourceObject"
}
}
},
"required": [
"data"
]
}
},
"required": [
"profile",
"events"
]
}
},
"required": [
"type",
"attributes"
]
},
"MetricCreateQueryResourceObject": {
"type": "object",
"properties": {
"type": {
"$ref": "#/components/schemas/MetricEnum"
},
"attributes": {
"type": "object",
"properties": {
"name": {
"description": "Name of the event. Must be less than 128 characters.",
"type": "string",
"example": "Viewed Product"
},
"service": {
"description": "This is for advanced usage. For api requests, this should use the default, which is set to api.",
"type": "string",
"nullable": true
}
},
"required": [
"name"
]
}
},
"required": [
"type",
"attributes"
]
},
"MetricEnum": {
"type": "string",
"enum": [
"metric"
]
},
"OnsiteProfileCreateQueryResourceObject": {
"type": "object",
"properties": {
"type": {
"$ref": "#/components/schemas/ProfileEnum"
},
"id": {
"description": "Primary key that uniquely identifies this profile. Generated by Klaviyo.",
"type": "string",
"nullable": true
},
"attributes": {
"type": "object",
"properties": {
"email": {
"description": "Individual's email address",
"type": "string",
"example": "sarah.mason@klaviyo-demo.com",
"nullable": true
},
"phone_number": {
"description": "Individual's phone number in E.164 format",
"type": "string",
"example": "+15005550006",
"nullable": true
},
"external_id": {
"description": "A unique identifier used by customers to associate Klaviyo profiles with profiles in an external system, such as a point-of-sale system. Format varies based on the external system.",
"type": "string",
"nullable": true
},
"anonymous_id": {
"type": "string",
"nullable": true
},
"_kx": {
"description": "Also known as the `exchange_id`, this is an encrypted identifier used for identifying a\nprofile by Klaviyo's web tracking.\n\nYou can use this field as a filter when retrieving profiles via the Get Profiles endpoint.",
"type": "string",
"nullable": true
},
"first_name": {
"description": "Individual's first name",
"type": "string",
"example": "Sarah",
"nullable": true
},
"last_name": {
"description": "Individual's last name",
"type": "string",
"example": "Mason",
"nullable": true
},
"organization": {
"description": "Name of the company or organization within the company for whom the individual works",
"type": "string",
"example": "Example Corporation",
"nullable": true
},
"locale": {
"description": "The locale of the profile, in the IETF BCP 47 language tag format like (ISO 639-1/2)-(ISO 3166 alpha-2)",
"type": "string",
"example": "en-US",
"nullable": true
},
"title": {
"description": "Individual's job title",
"type": "string",
"example": "Regional Manager",
"nullable": true
},
"image": {
"description": "URL pointing to the location of a profile image",
"type": "string",
"example": "https://images.pexels.com/photos/3760854/pexels-photo-3760854.jpeg",
"nullable": true
},
"location": {
"$ref": "#/components/schemas/ProfileLocation",
"nullable": true
},
"properties": {
"description": "An object containing key/value pairs for any custom properties assigned to this profile",
"type": "object",
"example": {
"pseudonym": "Dr. Octopus"
},
"nullable": true
}
}
},
"meta": {
"$ref": "#/components/schemas/OnsiteProfileMeta",
"nullable": true
}
},
"required": [
"type",
"attributes"
]
},
"OnsiteProfileMeta": {
"type": "object",
"properties": {
"patch_properties": {
"description": "Specify one or more patch operations to apply to existing property data",
"example": {
"append": {
"skus": "92538"
}
},
"$ref": "#/components/schemas/ProfileMetaPatchProperties",
"nullable": true
},
"patch_identifiers": {
"description": "Specify one or more patch operations to apply to existing identifier data. Currently only `email` is supported, and it is used to add or remove secondary email addresses on a profile.",
"example": {
"append": {
"email": [
"example@test.com",
"another@example.com"
]
}
},
"$ref": "#/components/schemas/PatchIdentifiers",
"nullable": true
}
}
},
"PatchIdentifiers": {
"type": "object",
"properties": {
"append": {
"type": "object"
},
"unappend": {
"type": "object"
}
}
},
"ProfileEnum": {
"type": "string",
"enum": [
"profile"
]
},
"ProfileLocation": {
"type": "object",
"properties": {
"address1": {
"description": "First line of street address",
"type": "string",
"example": "89 E 42nd St",
"nullable": true
},
"address2": {
"description": "Second line of street address",
"type": "string",
"example": "1st floor",
"nullable": true
},
"city": {
"description": "City name",
"type": "string",
"example": "New York",
"nullable": true
},
"country": {
"description": "Country name",
"type": "string",
"example": "United States",
"nullable": true
},
"latitude": {
"description": "Latitude coordinate. We recommend providing a precision of four decimal places.",
"example": "40.7128",
"nullable": true,
"oneOf": [
{
"type": "string"
},
{
"type": "number"
}
]
},
"longitude": {
"description": "Longitude coordinate. We recommend providing a precision of four decimal places.",
"example": "74.0060",
"nullable": true,
"oneOf": [
{
"type": "string"
},
{
"type": "number"
}
]
},
"region": {
"description": "Region within a country, such as state or province",
"type": "string",
"example": "NY",
"nullable": true
},
"zip": {
"description": "Zip code",
"type": "string",
"example": "10017",
"nullable": true
},
"timezone": {
"description": "Time zone name. We recommend using time zones from the IANA Time Zone Database.",
"type": "string",
"example": "America/New_York",
"nullable": true
},
"ip": {
"description": "IP Address",
"type": "string",
"example": "127.0.0.1",
"nullable": true
}
}
},
"ProfileMetaPatchProperties": {
"type": "object",
"properties": {
"append": {
"description": "Append a simple value or values to this property array",
"type": "object",
"example": {
"skus": "92538"
},
"nullable": true
},
"unappend": {
"description": "Remove a simple value or values from this property array",
"type": "object",
"example": {
"skus": "40571"
},
"nullable": true
},
"unset": {
"description": "Remove a key or keys (and their values) completely from properties",
"example": "skus",
"nullable": true,
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
}
}
}
},
"securitySchemes": {
"Klaviyo-API-Key": {
"type": "apiKey",
"in": "header",
"name": "Authorization",
"description": "Private key authentication for /api/ endpoints is performed by setting the `Authorization` header to `Klaviyo-API-Key your-private-api-key`
For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#authentication",
"x-default": "Klaviyo-API-Key your-private-api-key"
}
}
},
"tags": [
{
"name": "Events",
"description": "events"
}
]
}