Solution Recipe: Append, unappend, and unset custom properties programmatically with Klaviyo

9 min read

October 24, 2023

Note: We do our best to make sure any code and API references are accurate and current when this is published, but you might need to update code and it’s always a best practice to leverage our latest API versions. If you have questions, feel free to hop over to our Developer Community.

What you’ll learn

Explore Klaviyo’s update profile endpoint and learn how to programmatically append, unappend, and unset custom properties with concrete payload request examples.

Level of sophistication

Moderate

Introduction

As part of Klaviyo’s new API‘s release, we’ve also improved capabilities within the update profile endpoint. This functionality significantly expands the range of possibilities for data manipulation for the developers using Klaviyo’s APIs.

This Solution Recipe goes over Klaviyo’s various use cases and nuances on how to seamlessly use the update profile endpoint to append, unappend, and unset properties.

Challenge

Appending custom properties allows Klaviyo users to ingest more data points into existing customer profiles in a more structured way. For instance, if the customer fills out a survey on the company website, the collected data can be easily appended to customer profile properties in Klaviyo. This helps Klaviyo users not only refine data collection processes, but also craft more personalized content for their audience.

Note: A profile property should initially be an array for the append functionality to work properly. If it’s a string, the request will be silently ignored.

For example, if you append the country property (a string), it will lead to an ignored request. However, if the country is presented as an array, the payload request will be successful. On the other hand, the unset object doesn’t have to be an array in order to successfully implement it.

The unappend feature facilitates the removal of specific data points from arrays. For instance, let’s say a user on a content-based platform decides to unfollow a channel. Using the unappend feature, businesses can seamlessly reflect these changes in the customer’s profile programmatically.

Sometimes, simply appending or unappending doesn’t suffice. There are instances where data points need to be entirely removed from a customer’s profile. Here’s where the unset functionality comes into play—and it can be a game-changer for businesses that need to remain compliant with data privacy regulations.

Instructions

For the more tech-savvy readers, let’s look at some examples.

We will fist need to make a Get Profile call in order to fetch the profile metadata that we want to change.
Here is the payload response example for the Get Profile endpoint :

{
    "data": {
        "type": "profile",
        "id": "01H1VZPFHQQ8M13AC6Z3D9HYNX",
        "attributes": {
            "email": "jonathan.smith888@test.com",
            "phone_number": "5551234567",
            "external_id": null,
            "anonymous_id": null,
            "first_name": "John",
            "last_name": "Smith",
            "organization": null,
            "title": null,
            "image": null,
            "created": "2023-06-01T17:22:14+00:00",
            "updated": "2023-07-26T21:16:32+00:00",
            "last_event_date": "2023-06-01T17:22:13+00:00",
            "location": {
                "address1": null,
                "address2": null,
                "city": null,
                "country": null,
                "latitude": null,
                "longitude": null,
                "region": null,
                "zip": null,
                "timezone": null,
                "ip": null
            },
            "properties": {
                "address1": "123 Abc st",
                "address2": "Suite 1",
                "country": "USA",
                "newKey": "New Value",
                "states": [
                    "MA",
                    "CA"
                ],
                "teams": [
                    "RD",
                    "RedSox",
                    "SA"
                ]
            }
        },
        "relationships": {
            "lists": {
                "links": {
                    "self": "https://a.klaviyo.com/api/profiles/01H1VZPFHQQ8M13AC6Z3D9HYNX/relationships/lists/",
                    "related": "https://a.klaviyo.com/api/profiles/01H1VZPFHQQ8M13AC6Z3D9HYNX/lists/"
                }
            },
            "segments": {
                "links": {
                    "self": "https://a.klaviyo.com/api/profiles/01H1VZPFHQQ8M13AC6Z3D9HYNX/relationships/segments/",
                    "related": "https://a.klaviyo.com/api/profiles/01H1VZPFHQQ8M13AC6Z3D9HYNX/segments/"
                }
            }
        },
        "links": {
            "self": "https://a.klaviyo.com/api/profiles/01H1VZPFHQQ8M13AC6Z3D9HYNX/"
        }
    }
}

Append property use case example
In this example, we will append custom properties for teams to better understand how it all works.

Let’s say we want to append above values and add Houston Astros to the team.

Now, we’d need to send the Update Profile endpoint in , get the 200 OK status and check the UI to confirm the results. This is what the payload would look like if we were to append teams property.

{
"data": {
"type": "profile",
"id": "01H1VZPFHQQ8M13AC6Z3D9HYNX",
"attributes": {
"properties": {
},
"email": "jonathan.smith888@test.com"
},
"meta": {
      "patch_properties": {
        "append": {
          "teams": "Houston Astros"

We can see that “Houston Astros” got added to the list.

Nuance worth noting: Once an array is established, you can append a string as a value to it.

Let’s discuss another example to ensure that the use-cases are clear. Let’s say a retail business tracks product categories a customer has shown interest in making personalized product recommendations. Every time a customer clicks on a new category, the company can append that category to the customer’s profile in Klaviyo. For instance, if a customer first clicked on “Books” and later on “Electronics”, the customer’s profile property for “Interested Categories” might look like [“Books”, “Electronics”].

Here is the payload example and what it would look like:

Request:

curl --request PATCH \
     --url https://a.klaviyo.com/api/profiles/12344553/ \
     --header 'Authorization: Klaviyo-API-Key Your Private API Keys' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'revision: 2023-08-15' \
     --data '
{
  "data": {
    "type": "profile",
    "id": "12344553",
    "attributes": {
      ...
    },
    "meta": {
      "patch_properties": {
        "append": {
          "Interested Categories": "Electronics"
        }
      }
    }
  }
}'

Response payload:

{

"Interested Categories": ["Books", "Electronics"]

}

To reiterate, if you’re working with an existing custom property that is not a list, you’ll first need to update it to be a list to be able to take advantage of the append functionality. If starting fresh, you can just always use “append”, which will create the property if it doesn’t exist, or append to it if it does exist.

If you want to update this field when creating an event, you should be able to follow a similar pattern using the profile.meta.append object.

Unappending custom properties

While appending data is a beneficial tool, there are some data points that may become irrelevant over time. In such cases, the ability to unappend custom properties can help businesses maintain accurate and up-to-date information about their audience.
Below is an “unappend” use-case example showcasing the same profile and properties as discussed above for the append properties.
Le’t say we want to unappend the “RD” value from teams. What we will need to do is simply call the Update Profile endpoint and specify the object that we want to unappend.

Once the call is made with the above specifications, we’ll see that the “RD” has been removed from the teams values.

Another use-case for the “unappend” object would be if the customer unsubscribes from a specific service or changes their preferences, the associated data can be removed from their profile, keeping the customer database clean and relevant. If the profile uses a subscription platform where they can follow various content channels or creators and decide to unfollow a channel or creator, the business might want to remove that channel or creator from the user’s “Followed Channels” list. If a user initially followed channels A, B, and C, and later unfollowed B, the profile’s “Followed Channels” property might be updated from [“A”, “B”, “C”] to [“A”, “C”] using the unappend option.
For example, here is what it’d look like if we were to send a payload request and get a response programmatically.

Request payload:

curl --request PATCH \
     --url https://a.klaviyo.com/api/profiles/1234567/ \
     --header 'Authorization: Klaviyo-API-Key Klaviyo API Keys' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'  \
     --header 'revision: 2023-08-15' \
     --data '
{
  "data": {
    "type": "profile",
    "id": "123456",
    "attributes": {
      ...
    },
    "meta": {
      "patch_properties": {
        "unappend": {
          "Followed Channels": "B"
        }
      }
    }
  }
}'

Response:

{
  "Followed Channels": ["A", "C"]
}

Unset Custom Properties

In addition to appending and unappending, unsetting custom properties can also be useful, particularly when a business needs to remove specific data entirely from a customer’s profile.
If a customer opts to delete their account, the associated data can be unset, ensuring compliance with data privacy regulations and further enhancing the company’s data management practices.
For example, let’s say we want to unset the “teams” property from a profile entirely.
Here is the example payload below:

curl --request PATCH \
     --url https://a.klaviyo.com/api/profiles/01H1VZPFHQQ8M13AC6Z3D9HYNX/ \
     --header 'Authorization: Klaviyo-API-Key pk_a587bca931b6e62e08f97d627cd438b6b5' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'revision: 2023-10-15' \
     --data '
{
  "data": {
    "type": "profile",
    "id": "01H1VZPFHQQ8M13AC6Z3D9HYNX",
    "attributes": {
      "email": "jonathan.smith888@test.com",
      "first_name": "John",
      "last_name": "Smith",
      "title": "Engineer",
      "image": "https://images.pexels.com/photos/3760854/pexels-photo-3760854.jpeg",
      "location": {
        "address1": "89 E 42nd St",
        "address2": "1st floor",
        "city": "New York",
        "country": "United States",
        "region": "NY",
        "zip": "10017",
        "timezone": "America/New_York",
        "ip": "127.0.0.1"
      },
      "properties": {
        "newKey": "New Value"
      }
    },
    "meta": {
      "patch_properties": {
        "append": {
          "teams": "Houston Astros"
        },
        "unappend": {
          "teams": "RD"
        },
        "unset": "teams"
      }
    }
  }
}
'

Response:

The payload request above removed teams entirely.

Impact

Klaviyo Update Profile API’s ability to append, unappend and unset profile properties empowers users with more sophisticated and efficient tools for data management and the ability to create highly personalized campaign or flow messages. By having the flexibility to easily adjust user profile data, businesses can ensure that every message sent to the user, whether it’s a promotional email, a product recommendation, or a service update, is tailored to their unique needs and preferences. This results in increased engagement, better customer satisfaction, and potentially higher conversion rates.With real-time data adjustments, campaigns and flows (automated email sequences or messaging paths) can dynamically change based on the latest user data. Klaviyo API’s abilities to manipulate profile properties enhance the platform’s adaptability and effectiveness to its full potential!

Nina Ephremidze

Saul Blumenthal