Klaviyo: configurable batch size (#3650)

* Make Klaviyo batch_size configurable in UI

- Set unsafe_hidden to false to make batch_size visible in UI
- Add minimum constraint of 100 to prevent too-small batches
- Add maximum constraint of 10,000 (Klaviyo API limit)
- Update description with recommendations for RETL sources (500-1000) and event streams (5000-10000)

This enables customers to adjust batch sizes for their specific use cases, particularly RETL sources that may need smaller batch sizes to avoid payload rejections.

* Add batch_bytes field to Klaviyo batching actions

- Add batch_bytes to properties.ts with 5MB max (Klaviyo API limit)
- Add batch_bytes to all actions using profile-bulk-import-jobs API:
  - upsertProfile
  - addProfileToList
  - trackEvent
  - removeProfile
  - removeProfileFromList
- Default: 4MB to stay safely below 5MB limit
- Note known RETL limitations in field description

* Keep batch_bytes hidden (unsafe_hidden: true)

batch_bytes has known limitations with RETL and generally should not be exposed to customers per framework guidance. Only batch_size needs to be visible.

* Remove batch_bytes from actions not using profile-bulk-import-jobs API

batch_bytes with 5MB limit only applies to profile-bulk-import-jobs API.
Removed from:
- trackEvent (uses event-bulk-create-jobs API)
- removeProfile (uses DELETE operations)
- removeProfileFromList (uses DELETE operations)

batch_bytes remains only in:
- upsertProfile (uses profile-bulk-import-jobs)
- addProfileToList (uses profile-bulk-import-jobs)

* Fix: Remove batch_bytes from addProfileToList perform method

batch_bytes is only used by platform batching layer, not in single-event perform method

* Fix: Exclude batch_bytes from upsertProfile API payload

batch_bytes and batch_size are platform-level batching controls and should not be sent to Klaviyo API as profile attributes

* Remove min/max constraints from batch_size and batch_bytes

Test data generator doesn't respect min/max constraints, and no other destination uses them for batch fields. The field descriptions already document recommended values and Klaviyo's limits (10K profiles, 5MB payload).

* Update test data generator to respect min/max constraints

Modified test-data.ts to:
- Accept minimum/maximum parameters in setTestData function
- Use Chance.js min/max options when generating integer/number values
- Pass minimum/maximum from field definitions through all callers

Re-added min/max constraints to Klaviyo batch fields:
- batch_size: min 100, max 10000
- batch_bytes: min 100000, max 5000000

This ensures generated test data respects field validation constraints.

* Update generated types for Klaviyo batch field constraints

* Fix timezone-based test failures in snapshot tests

Apply deterministic UTC timestamp generation for date-time fields to avoid CI failures due to timezone differences between local and CI environments. This fixes Braze ecommerceSingleProduct snapshot test failures.

Credit: Adapted from commit 4664041 by Sayan Das

* Remove min/max from hidden batch_bytes field and simplify batch_size description

- Remove minimum/maximum constraints from batch_bytes (field is hidden, constraints not needed)
- Simplify batch_size description to match standard pattern
- Keep batch_size default at 10000 with min/max constraints (100-10000)

* update types

* Remove batch_bytes field - platform default of 4MB is sufficient

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* Set minimum to 100 for all

* Fix test-data min/max handling and revert timezone workaround

- Use conditional spread in setTestData to avoid passing undefined min/max to chance
- Revert date-time generation back to chance.date().toISOString()
- Revert braze snapshot to original values
- Document TZ=UTC requirement in CLAUDE.md

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

* Show batch_size field only when enable_batching is true

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

* update batch size for subscribe and unsubscribe profile actions

---------

Co-authored-by: Claude Opus 4.6 <[email protected]>

Author: varadarajan-tw

CLAUDE.md

@@ -58,6 +58,8 @@ yarn browser jest --testPathPattern="braze"
 yarn core jest --testPathPattern="mapping-kit"
 ```
 
+> **Note:** Always run tests with `TZ=UTC` (e.g. `TZ=UTC yarn cloud test`) to ensure snapshot tests produce consistent results regardless of local timezone.
+
 ### Lint & Type Checking
 
 ```bash
@@ -179,10 +181,62 @@ To override automatic HTTP error handling, set `throwHttpErrors: false` on the r
 
 ### Batching
 
+**Important**: Batching is handled by a component within Segment BEFORE your `performBatch` method is called. You do not need to implement chunking logic in your destination code.
+
 - Implement `performBatch` for high-volume destinations
 - Use appropriate batch keys with low cardinality to avoid inefficient batching
 - Test various batch sizes and edge cases
 
+#### batch_size vs batch_bytes
+
+Both fields control how Segment's platform groups events before calling your `performBatch` method:
+
+**batch_size** (recommended for customer exposure with caution):
+
+- Controls the maximum **number of events** in a batch
+- Default: 1000 events (subject to change)
+- Use when: Destination API has limits on number of records per request
+- Customer exposure: Use judgement - expose only when necessary (e.g., RETL sources with large records)
+- Always enforce min/max validation when exposed (e.g., `minimum: 100, maximum: 10000`)
+
+**batch_bytes** (generally should NOT be exposed):
+
+- Controls the maximum **payload size in bytes** of a batch
+- Default: 4MB (subject to change)
+- Use when: Destination API has strict request body size limits
+- Customer exposure: Avoid exposing to customers - can significantly impact delivery performance
+- Keep `unsafe_hidden: true` by default
+
+**Example field definitions**:
+
+```typescript
+fields: {
+  batch_size: {
+    label: 'Batch Size',
+    description: 'Maximum number of events to include in each batch.',
+    type: 'number',
+    unsafe_hidden: false,  // Only expose if customers need control
+    default: 10000,
+    minimum: 100,
+    maximum: 10000,
+    required: false
+  },
+  batch_bytes: {
+    label: 'Batch Bytes',
+    description: 'Maximum size of a batch in bytes.',
+    type: 'number',
+    unsafe_hidden: true,  // Avoid exposing to customers
+    default: 2000000,  // 2MB
+    required: false
+  }
+}
+```
+
+**Batching behavior**:
+
+- Batch sizes are not guaranteed - may be smaller than configured limit
+- Lower event volumes = smaller actual batch sizes
+
 ### Security
 
 - Never expose or log sensitive information like auth tokens or PII

packages/destination-actions/src/destinations/klaviyo/addProfileToList/index.ts

@@ -29,7 +29,7 @@ const action: ActionDefinition<Settings, Payload> = {
     list_id: { ...list_id },
     external_id: { ...external_id },
     enable_batching: { ...enable_batching },
-    batch_size: { ...batch_size },
+    batch_size: { ...batch_size, default: 10000, minimum: 100, maximum: 10000 },
     first_name: { ...first_name },
     last_name: { ...last_name },
     image: { ...image },

packages/destination-actions/src/destinations/klaviyo/properties.ts

@@ -46,8 +46,16 @@ export const batch_size: InputField = {
   description: 'Maximum number of events to include in each batch. Actual batch sizes may be lower.',
   type: 'number',
   required: false,
-  unsafe_hidden: true,
-  default: 10000
+  unsafe_hidden: false,
+  depends_on: {
+    conditions: [
+      {
+        fieldKey: 'enable_batching',
+        operator: 'is',
+        value: true
+      }
+    ]
+  }
 }
 
 export const first_name: InputField = {

packages/destination-actions/src/destinations/klaviyo/removeProfile/index.ts

@@ -36,7 +36,7 @@ const action: ActionDefinition<Settings, Payload> = {
       required: true
     },
     enable_batching: { ...enable_batching },
-    batch_size: { ...batch_size, default: 1000 },
+    batch_size: { ...batch_size, default: 1000, minimum: 100, maximum: 1000 },
     phone_number: {
       label: 'Phone Number',
       description: `Individual's phone number in E.164 format. If SMS is not enabled and if you use Phone Number as identifier, then you have to provide one of Email or External ID.`,

packages/destination-actions/src/destinations/klaviyo/removeProfileFromList/index.ts

@@ -16,7 +16,7 @@ const action: ActionDefinition<Settings, Payload> = {
     phone_number: { ...phone_number },
     enable_batching: { ...enable_batching },
     country_code: { ...country_code },
-    batch_size: { ...batch_size, default: 1000 },
+    batch_size: { ...batch_size, default: 1000, minimum: 100, maximum: 1000 },
     batch_keys: {
       label: 'Batch Keys',
       description: 'The keys to use for batching the events.',

packages/destination-actions/src/destinations/klaviyo/subscribeProfile/generated-types.ts

@@ -7,7 +7,7 @@ import { PayloadValidationError } from '@segment/actions-core'
 import { formatSubscribeProfile, formatSubscribeRequestBody } from '../functions'
 import { SubscribeProfile } from '../types'
 import { API_URL } from '../config'
-import { country_code } from '../properties'
+import { batch_size, country_code } from '../properties'
 
 const action: ActionDefinition<Settings, Payload> = {
   title: 'Subscribe Profile',
@@ -82,6 +82,12 @@ const action: ActionDefinition<Settings, Payload> = {
       required: false,
       multiple: true,
       default: ['list_id', 'custom_source', 'historical_import']
+    },
+    batch_size: {
+      ...batch_size,
+      default: 1000,
+      minimum: 100,
+      maximum: 1000
     }
   },
   dynamicFields: {

packages/destination-actions/src/destinations/klaviyo/subscribeProfile/index.ts

@@ -94,7 +94,7 @@ const action: ActionDefinition<Settings, Payload> = {
       }
     },
     enable_batching: { ...enable_batching },
-    batch_size: { ...batch_size, default: 1000 }
+    batch_size: { ...batch_size, default: 1000, minimum: 100, maximum: 1000 }
   },
   perform: (request, { payload }) => {
     const { email, phone_number: initialPhoneNumber, external_id, anonymous_id, country_code } = payload.profile

packages/destination-actions/src/destinations/klaviyo/trackEvent/index.ts

@@ -6,7 +6,7 @@ import { PayloadValidationError } from '@segment/actions-core'
 import { formatUnsubscribeProfile, formatUnsubscribeRequestBody } from '../functions'
 import { UnsubscribeProfile } from '../types'
 import { API_URL } from '../config'
-import { country_code } from '../properties'
+import { country_code, batch_size } from '../properties'
 
 const action: ActionDefinition<Settings, Payload> = {
   title: 'Unsubscribe Profile',
@@ -60,6 +60,12 @@ const action: ActionDefinition<Settings, Payload> = {
       required: false,
       multiple: true,
       default: ['list_id']
+    },
+    batch_size: {
+      ...batch_size,
+      default: 100,
+      minimum: 50,
+      maximum: 100
     }
   },
   dynamicFields: {