Sometimes the data you need already exists somewhere else, but Klaviyo doesn’t have it.

You might have:

• language stored in separate lists;
• customer type in Shopify;
• membership status in another platform;
• acquisition source in a spreadsheet;
• subscription state in an external system;
• an old CRM field that wasn’t carried across during migration.

If the number of profiles is small, you can update them manually.

If you have hundreds or thousands, the Klaviyo API is usually a better option.

A bulk profile update lets you take something like:

Email address → required property value

and systematically write that information back to the matching Klaviyo profiles.

A practical example: adding language to Klaviyo profiles

A recent use case was language.

Imagine customers have been imported into Klaviyo from several language-specific lists:

• Portuguese;
• German;
• French;
• Spanish.

The profiles are there, but their language hasn't been carried across.

That means Klaviyo knows:

this person exists

but doesn't know:

this person should receive Portuguese content.

Rather than rebuilding the migration, we can update the existing profiles.

For example:

language = pt

or:

locale = pt

Once that property exists, it can be used for:

• segmentation;
• campaign targeting;
• multilingual flows;
• conditional splits;
• dynamic content;
• reporting.

This is exactly the kind of situation where the API is useful.

The basic workflow

The process looks like this:

Source data

↓

Identify the Klaviyo profile

↓

Send the new property

↓

Klaviyo updates the profile

↓

QA the result

For a language update, the source might simply be a CSV containing:

Your script then works through those records and updates the corresponding profiles in Klaviyo.

What can you update?

Klaviyo profile properties can hold information such as:

preferred_language

customer_type

membership_status

subscription_status

acquisition_source

lifecycle_stage

preferred_category

store_location

or almost any other customer-level field your CRM programme needs.

The important distinction is that these should represent information about the customer, rather than details of a single action they performed.

For more on that distinction, read:

Customer Properties vs Event Properties in Klaviyo: What’s the Difference?

Updating one profile vs thousands

Klaviyo provides different API approaches depending on the size of the job.

For individual or smaller synchronous updates, Klaviyo's profile APIs can create or update a profile and its custom properties.

For larger jobs, Klaviyo provides a Bulk Import Profiles API, which performs an upsert: existing matching profiles are updated, while profiles that don't already exist can be created. Klaviyo currently recommends the bulk endpoint for larger profile imports and updates rather than small numbers of profiles.

That means the architecture can scale from:

Update this customer's property

to:

Update this property across thousands of customers.

What does the API actually send?

At a simplified level, you're telling Klaviyo:

Find this profile and add or update these properties.

Conceptually, the payload looks like:

{
  "email": "customer@example.com",
  "properties": {
    "preferred_language": "pt"
  }
}

The API then associates that property with the relevant profile.

You could just as easily send:

{
  "email": "customer@example.com",
  "properties": {
    "customer_type": "VIP"
  }
}

or several properties at once.

The current Klaviyo profile APIs support writing custom properties through the profile properties object.

Why use an API instead of uploading another CSV?

Sometimes a CSV upload is completely adequate.

But APIs become useful when you want the process to be:

Repeatable

The same script can be run again for another market or dataset.

Controlled

You can define exactly which field is changed.

Testable

Run it on a small group first.

Automated

Eventually the update can happen without somebody manually importing a file.

Connected

The source can be Shopify, another CRM, a database or another application rather than a spreadsheet.

That makes API-based profile updates particularly useful when you're building an ongoing CRM data architecture rather than doing a one-off cleanup.

Start with a small test

I would almost never begin by running a new update against the entire customer database.

Start with something small.

For example:

Portuguese list

↓

Select a handful of profiles

↓

Update:

locale = pt

↓

Open those profiles in Klaviyo

↓

Confirm the property and value are correct

Only then expand the update.

This gives you a chance to catch:

• incorrect property names;
• wrong property types;
• mismatched profiles;
• unexpected values;
• formatting problems;

before affecting thousands of records.

Check the property type

This is easy to overlook.

These aren't equivalent:

has_active_subscription = true

and:

has_active_subscription = "true"

One is a Boolean.

One is text.

Likewise, a date should ideally behave as a date if you intend to use it for date-based segmentation or automation.

Before running the update, decide what the field represents and how Klaviyo needs to use it.

The structure of your data should follow the CRM use case.

Don't overwrite more than you need

If you're updating language, update language.

You don't need to resend every other piece of profile data just because it exists in your source file.

A useful principle is:

Only change the properties the job is responsible for changing.

Klaviyo's current profile-update behaviour leaves fields you don't include unchanged. For synchronous profile updates, explicitly sending null can clear a field; the bulk import endpoint behaves differently and doesn't use null to clear existing values.

This matters if you're designing scripts that could affect important profile data.

QA after the update

Once the script has run, don't stop at:

It returned successfully.

Check the actual CRM.

I would verify:

Individual profiles

Did the property appear correctly?

Property type

Is the value stored in the format you expected?

Segments

If the property drives a segment, did the profile enter it?

Control profiles

Did profiles outside the update remain unchanged?

Counts

Does the number of updated profiles broadly match the number you expected?

For high-impact changes, export or record the original state before running the update so you have something to compare against.

What can you do with the property afterwards?

The API update is only useful if the data enables something.

For example, adding:

preferred_language = pt

could allow you to build:

Portuguese customers

↓

Portuguese campaigns

↓

Portuguese Welcome Flow branch

↓

Portuguese dynamic content

The same model applies to:

customer_type = VIP

↓

VIP segmentation and messaging.

Or:

has_active_subscription = true

↓

subscriber campaigns and lifecycle flows.

The API handles the plumbing.

CRM strategy determines what the field is actually for.

When should this become an automated integration?

A one-off script is useful when fixing or enriching historical data.

But if the source property can keep changing, repeatedly running a script isn't the ideal long-term solution.

For example:

If subscription status changes every day, Shopify should send that change automatically.

If language is selected in an app, you may want that preference synced when it changes.

If loyalty tier changes based on spend, your CRM should receive the updated state automatically.

At that point, you're moving from:

bulk data update

to:

CRM integration.

For an example of that architecture, read:

How to Send Shopify Subscription Data to Klaviyo Using Shopify Flow

A useful rule

Use a bulk update when:

You have an existing group of customers whose profile data needs correcting or enriching.

Use an integration when:

The property will continue changing and Klaviyo needs to stay synchronised with another system.

Quite often, you need both.

Step 1

Backfill historical profiles.

Step 2

Turn on the integration for future changes.

That gives Klaviyo the correct starting state and keeps it correct afterwards.

Want the scripts and full setup?

I'm packaging this process into a Brutish Klaviyo Profile Properties API Guide, including reusable scripts and a safer framework for running bulk customer-data updates.

The full guide will cover:

• preparing your source data;
• identifying profiles;
• custom property structure;
• bulk API updates;
• batching;
• CSV processing;
• testing;
• error handling;
• QA;
• validation;
• multiple property updates;
• backfills;
• rollback planning;
• moving from a one-off update to an automated integration.

Join the waitlist to be notified when it's available.

Need Brutish to do it?

If you need to migrate, clean, backfill or connect customer data in Klaviyo, Brutish works across Klaviyo, Shopify and CRM integrations to turn fragmented customer data into something marketers can actually use.

Work with Brutish.