- SDK version: 6.0.0
- API revision: 2024-02-15
This SDK is a thin wrapper around our API. See our API Reference for full documentation on API behavior.
This SDK is organized into the following resources:
-
Accounts
-
Campaigns
-
Catalogs
-
Coupons
-
Data Privacy
-
Events
-
Flows
-
Images
-
Lists
-
Metrics
-
Profiles
-
Reporting
-
Segments
-
Tags
-
Templates
To build the Ruby code into a gem:
gem build klaviyo-api-sdk.gemspecThen install the gem locally:
gem install ./klaviyo-api-sdk-6.0.0.gemFinally add this to the Gemfile:
gem 'klaviyo-api-sdk', '~> 6.0.0'
To install directly from rubygems:
gem install klaviyo-api-sdk# Load the gem
require 'klaviyo-api-sdk'
# Setup authorization
KlaviyoAPI.configure do |config|
config.api_key['Klaviyo-API-Key'] = 'Klaviyo-API-Key your-api-key'
#config.max_retries = 5 # optional
#config.max_delay = 60 # optional
endNOTE:
- The SDK retries on resolvable errors, namely: rate limits (common) and server errors on klaviyo (rare).
max_retrydenotes number of attempts the client will make in order to execute the request successfully.max_delaydenotes total delay (in seconds) across all attempts.
opts = {
include: ['variants'],
sort: 'created',
filter: 'equals(published,false)',
fields_catalog_item: ['external_id','title']
}
begin
result = KlaviyoAPI::Catalogs.get_catalog_items(opts)
endThis SDK throws an ApiException error when the server returns a non-2XX response.
begin
result = KlaviyoAPI::Catalogs.get_catalog_items(opts)
rescue KlaviyoAPI::ApiError => e
puts "Error when calling get_catalog_items #{e}"
endgetoperations can be passed an optionaloptsobject (e.g.get_list_profiles(opts)).optsdescribes the available options for fetching data (some operations only support a subset of these or none). i.e.
opts = {
include: ['variants'], # includes
sort: '-created', # sorting
filter: 'equals(published,false)', # filters
page_cursor: 'page_cursor_example', # cursor pagination
fields_catalog_item: ['external_id','title'], # sparse fieldset
fields_catalog_variant: ['external_id','title'], # sparse fieldset
additional_fields_profile: ['predictive_analytics'], # for endpoints that support predictive analytics such as `get_profile`
}**Note, for parameters that use square brackets such as page[cursor] or fields[catalog-item] ruby will replace the square brackets [] with _ underscores.
- For
create,update& somedeleteoperations (i.e.create_catalog_itemorupdate_catalog_itemordelete_catalog_category_relationships) thebodyobject is required in the method signature (i.e.create_catalog_item(body)).
body = {
data: {
type: "catalog-item",
attributes: {
external_id: "catalog-item-test",
title: "Catalog Item Test",
description: "this is a description",
url: "http://catalog-item.klaviyo.com",
published: true
}
}
}
KlaviyoAPI::Catalogs.create_catalog_item(body)For uploading a file using the Images.upload_image_from_file simply pass in an opened file
result = KlaviyoAPI::Images.upload_image_from_file(File.open('test_file.jpg', 'r'))Here we will go over
- Pagination
- Page size
- Additional Fields
- Filtering
- Sparse Fields
- Sorting
- Relationships
As a reminder, the optional parameters are named slightly different from how you would make the call without the SDK docs, query parameter names have variables that make bad Ruby names like
page[cursor] are transformed to page_cursor.
All the endpoints that return list of results use cursor base pagination.
Obtain the cursor value from the call you want to get the next page for, then pass it under the page_cursor optional parameter. The page cursor looks like WzE2NDA5OTUyMDAsICIzYzRjeXdGTndadyIsIHRydWVd.
If you were using the api directly you would pass the cursor like:
https://a.klaviyo.com/api/profiles/?page[cursor]=WzE2NTcyMTM4NjQsICIzc042NjRyeHo0ciIsIHRydWVd
The same call in the sdk the call would look like this:
opts = {
page_cursor: 'WzE2NTcyMTM4NjQsICIzc042NjRyeHo0ciIsIHRydWVd',
}
response = KlaviyoAPI::Profiles.get_profiles(opts)You get the cursor for the next page from response[:links][:next] returns the entire url of the next call but the sdk will accept the entire link and use only the relevant cursor.
Here is an example of getting the second next and passing in the page cursor:
opts = {
page_cursor: response[:links][:next], # previous response
}
response = KlaviyoAPI::Profiles.get_profiles(opts)There are more page cursors than just next, check the endpoint's docs or the response type but often there is first, last, next and prev.
Some endpoint you can get a larger or smaller page size by using the page_size parameter.
if you were hitting the api directly this would look like
https://a.klaviyo.com/api/profiles/?page[size]=20
In the SDK this looks like:
opts = {
page_size: 20,
}
response = KlaviyoAPI::Profiles.get_profiles(opts)Additional fields are used to populate part of the response that would be null otherwise.
For the getProfile endpoint you can pass in a request to get the predictive analytics of the profile. Using the additional_fields parameter often will change the rate limit of the endpoint so be sure to keep an eye on your usage.
The url would look like:
https://a.klaviyo.com/api/profiles/01GDDKASAP8TKDDA2GRZDSVP4H/?additional-fields[profile]=predictive_analytics
The SDK equivalent is:
profile_id = '01GDDKASAP8TKDDA2GRZDSVP4H'
opts = {
additional_fields_profile: ["predictive_analytics"]
}
response = KlaviyoAPI::Profiles.get_profile(profile_id, opts)
# If your profile has enough information for predictive analytis it will populate
pp(response[:data][:attributes][:predictive_analytics])Filter by passing the filter as a string as under the optional parameter filter.
Read more about formatting your filter strings in our developer documentation
Here is an example of a filter string for results between two date times: less-than(updated,2023-04-26T00:00:00Z),greater-than(updated,2023-04-19T00:00:00Z)
Here is a code example filter for profiles with the matching emails:
https://a.klaviyo.com/api/profiles/?filter=any(email,["[email protected]","[email protected]"]
For the sdk:
opts = {
filter: 'any(email,["[email protected]","[email protected]"])'
}
response = KlaviyoAPI::Profiles.get_profiles(opts)If you only want a specific subset of data from a specific query you can use sparse fields to request only the specific properties. The SDK expands the optional sparse fields into their own option, where you can pass a list of the desired items to include.
To get a list of event properties the URL your would use is:
https://a.klaviyo.com/api/events/?fields[event]=event_properties
In the SDK you would use
opts = {
fields_event: ["event_properties"]
}
response = KlaviyoAPI::Events.get_events(opts)Your can request the results of specific endpoints to be ordered by a given parameter. The direction of the sort can swapped by adding a - in front of the sort key.
For example datetime will be ascending while -datetime will be descending.
If you are unsure about the available sort fields you can always check the documentation for the endpoint you are using. For a comprehensive list that links to the documentation for each function check the Endpoints section below.
Get events sorted by oldest to newest datetime.
https://a.klaviyo.com/api/events/?sort=-datetime
and via the sdk
opts = {
sort: '-datetime'
}
response = KlaviyoAPI::Events.get_events(opts)How to add additional information to your API response via additional-fields and the includes parameter.
This allows you to get information about two or more objects from a single api call.
Using the includes parameter often changes the rate limit of the endpoint so be sure to take note.
Using the URl to get profile information and the information about the lists the profile is in:
https://a.klaviyo.com/api/profiles/01GDDKASAP8TKDDA2GRZDSVP4H/?include=lists
In the sdk:
profile_id = '01GDDKASAP8TKDDA2GRZDSVP4H'
opts = {
include: ["lists"]
}
response = KlaviyoAPI::Profiles.get_profile(profile_id,opts)
# Profile information is accessed the same way with
pp(response[:data])
# Lists related to the profile with be accessible via the included array
pp(response[:included])Note about sparse fields and relationships: you can request only specific fields of the included object as well.
profile_id = '01GDDKASAP8TKDDA2GRZDSVP4H'
opts = {
fields_list: ["name"],
include: ["lists"]
}
response = KlaviyoAPI::Profiles.get_profile(profile_id,opts)
# Profile information is accessed the same way with
pp(response[:data])
# Lists related to the profile with be accessible via the included array
pp(response[:included])The Klaviyo Api has a series of endpoints to expose the relationships between your different Klaviyo Items. You can read more about relationships in our documentation.
Here are some use cases and their examples:
How to get the list memberships for a profile with the given profile ID.
Via the URL:
https://a.klaviyo.com/api/profiles/01GDDKASAP8TKDDA2GRZDSVP4H/relationships/lists/
and for the SDK:
profile_id = '01GDDKASAP8TKDDA2GRZDSVP4H'
response = KlaviyoAPI::Profiles.get_profile_relationships_lists(profile_id)For another example:
Get all campaigns associated with the given tag_id.
the URL:
https://a.klaviyo.com/api/tags/9c8db7a0-5ab5-4e3c-9a37-a3224fd14382/relationships/campaigns/
Through the SDK:
tag_id = '9c8db7a0-5ab5-4e3c-9a37-a3224fd14382'
response = KlaviyoAPI::Tags.get_tag_relationships_campaigns(tag_id)You can use any combination of the features outlines above in conjunction with one another.
Get events associated with a specific metric, then return just the event properties sorted by oldest to newest datetime.
https://a.klaviyo.com/api/events/?fields[event]=event_properties&filter=equals(metric_id,"URDbLg")&sort=-datetime
or
opts = {
filter: 'equals(metric_id,"URDbLg")',
fields_event: ["event_properties"]
}
response = KlaviyoAPI::Events.get_events(opts)NOTE:
- Organization: Resource groups and operation_ids are listed in alphabetical order, first by Resource name, then by OpenAPI Summary. Operation summaries are those listed in the right side bar of the API Reference.
- For example values / data types, as well as whether parameters are required/optional, please reference the corresponding API Reference link.
- Some args are required for the API call to succeed, the API docs above are the source of truth regarding which params are required.
KlaviyoAPI::Accounts.get_account(id, opts)KlaviyoAPI::Accounts.get_accounts(opts)KlaviyoAPI::Campaigns.create_campaign(body)KlaviyoAPI::Campaigns.create_campaign_clone(body)KlaviyoAPI::Campaigns.create_campaign_message_assign_template(body)KlaviyoAPI::Campaigns.create_campaign_recipient_estimation_job(body)KlaviyoAPI::Campaigns.create_campaign_send_job(body)KlaviyoAPI::Campaigns.delete_campaign(id)KlaviyoAPI::Campaigns.get_campaign(id, opts)KlaviyoAPI::Campaigns.get_campaign_campaign_messages(id, opts)KlaviyoAPI::Campaigns.get_campaign_message(id, opts)KlaviyoAPI::Campaigns.get_campaign_message_campaign(id, opts)KlaviyoAPI::Campaigns.get_campaign_message_relationships_campaign(id)KlaviyoAPI::Campaigns.get_campaign_message_relationships_template(id)KlaviyoAPI::Campaigns.get_campaign_message_template(id, opts)KlaviyoAPI::Campaigns.get_campaign_recipient_estimation(id, opts)KlaviyoAPI::Campaigns.get_campaign_recipient_estimation_job(id, opts)KlaviyoAPI::Campaigns.get_campaign_relationships_campaign_messages(id)KlaviyoAPI::Campaigns.get_campaign_relationships_tags(id)KlaviyoAPI::Campaigns.get_campaign_send_job(id, opts)KlaviyoAPI::Campaigns.get_campaign_tags(id, opts)KlaviyoAPI::Campaigns.get_campaigns(filter, opts)KlaviyoAPI::Campaigns.update_campaign(id, body)KlaviyoAPI::Campaigns.update_campaign_message(id, body)KlaviyoAPI::Campaigns.update_campaign_send_job(id, body)KlaviyoAPI::Catalogs.create_back_in_stock_subscription(body)KlaviyoAPI::Catalogs.create_catalog_category(body)KlaviyoAPI::Catalogs.create_catalog_category_relationships_items(id, body)KlaviyoAPI::Catalogs.create_catalog_item(body)KlaviyoAPI::Catalogs.create_catalog_item_relationships_categories(id, body)KlaviyoAPI::Catalogs.create_catalog_variant(body)KlaviyoAPI::Catalogs.delete_catalog_category(id)KlaviyoAPI::Catalogs.delete_catalog_category_relationships_items(id, body)KlaviyoAPI::Catalogs.delete_catalog_item(id)KlaviyoAPI::Catalogs.delete_catalog_item_relationships_categories(id, body)KlaviyoAPI::Catalogs.delete_catalog_variant(id)KlaviyoAPI::Catalogs.get_catalog_categories(opts)KlaviyoAPI::Catalogs.get_catalog_category(id, opts)KlaviyoAPI::Catalogs.get_catalog_category_items(id, opts)KlaviyoAPI::Catalogs.get_catalog_category_relationships_items(id, opts)KlaviyoAPI::Catalogs.get_catalog_item(id, opts)KlaviyoAPI::Catalogs.get_catalog_item_categories(id, opts)KlaviyoAPI::Catalogs.get_catalog_item_relationships_categories(id, opts)KlaviyoAPI::Catalogs.get_catalog_item_variants(id, opts)KlaviyoAPI::Catalogs.get_catalog_items(opts)KlaviyoAPI::Catalogs.get_catalog_variant(id, opts)KlaviyoAPI::Catalogs.get_catalog_variants(opts)KlaviyoAPI::Catalogs.get_create_categories_job(job_id, opts)KlaviyoAPI::Catalogs.get_create_categories_jobs(opts)KlaviyoAPI::Catalogs.get_create_items_job(job_id, opts)KlaviyoAPI::Catalogs.get_create_items_jobs(opts)KlaviyoAPI::Catalogs.get_create_variants_job(job_id, opts)KlaviyoAPI::Catalogs.get_create_variants_jobs(opts)KlaviyoAPI::Catalogs.get_delete_categories_job(job_id, opts)KlaviyoAPI::Catalogs.get_delete_categories_jobs(opts)KlaviyoAPI::Catalogs.get_delete_items_job(job_id, opts)KlaviyoAPI::Catalogs.get_delete_items_jobs(opts)KlaviyoAPI::Catalogs.get_delete_variants_job(job_id, opts)KlaviyoAPI::Catalogs.get_delete_variants_jobs(opts)KlaviyoAPI::Catalogs.get_update_categories_job(job_id, opts)KlaviyoAPI::Catalogs.get_update_categories_jobs(opts)KlaviyoAPI::Catalogs.get_update_items_job(job_id, opts)KlaviyoAPI::Catalogs.get_update_items_jobs(opts)KlaviyoAPI::Catalogs.get_update_variants_job(job_id, opts)KlaviyoAPI::Catalogs.get_update_variants_jobs(opts)KlaviyoAPI::Catalogs.spawn_create_categories_job(body)KlaviyoAPI::Catalogs.spawn_create_items_job(body)KlaviyoAPI::Catalogs.spawn_create_variants_job(body)KlaviyoAPI::Catalogs.spawn_delete_categories_job(body)KlaviyoAPI::Catalogs.spawn_delete_items_job(body)KlaviyoAPI::Catalogs.spawn_delete_variants_job(body)KlaviyoAPI::Catalogs.spawn_update_categories_job(body)KlaviyoAPI::Catalogs.spawn_update_items_job(body)KlaviyoAPI::Catalogs.spawn_update_variants_job(body)KlaviyoAPI::Catalogs.update_catalog_category(id, body)KlaviyoAPI::Catalogs.update_catalog_category_relationships_items(id, body)KlaviyoAPI::Catalogs.update_catalog_item(id, body)KlaviyoAPI::Catalogs.update_catalog_item_relationships_categories(id, body)KlaviyoAPI::Catalogs.update_catalog_variant(id, body)KlaviyoAPI::Coupons.create_coupon(body)KlaviyoAPI::Coupons.create_coupon_code(body)KlaviyoAPI::Coupons.delete_coupon(id)KlaviyoAPI::Coupons.delete_coupon_code(id)KlaviyoAPI::Coupons.get_coupon(id, opts)KlaviyoAPI::Coupons.get_coupon_code(id, opts)KlaviyoAPI::Coupons.get_coupon_code_bulk_create_job(job_id, opts)KlaviyoAPI::Coupons.get_coupon_code_bulk_create_jobs(opts)KlaviyoAPI::Coupons.get_coupon_code_relationships_coupon(id, opts)KlaviyoAPI::Coupons.get_coupon_codes(opts)KlaviyoAPI::Coupons.get_coupon_codes_for_coupon(id, opts)KlaviyoAPI::Coupons.get_coupon_for_coupon_code(id, opts)KlaviyoAPI::Coupons.get_coupon_relationships_coupon_codes(id)KlaviyoAPI::Coupons.get_coupons(opts)KlaviyoAPI::Coupons.spawn_coupon_code_bulk_create_job(body)KlaviyoAPI::Coupons.update_coupon(id, body)KlaviyoAPI::Coupons.update_coupon_code(id, body)KlaviyoAPI::DataPrivacy.request_profile_deletion(body)KlaviyoAPI::Events.create_event(body)KlaviyoAPI::Events.get_event(id, opts)KlaviyoAPI::Events.get_event_metric(id, opts)KlaviyoAPI::Events.get_event_profile(id, opts)KlaviyoAPI::Events.get_event_relationships_metric(id)KlaviyoAPI::Events.get_event_relationships_profile(id)KlaviyoAPI::Events.get_events(opts)KlaviyoAPI::Flows.get_flow(id, opts)KlaviyoAPI::Flows.get_flow_action(id, opts)KlaviyoAPI::Flows.get_flow_action_flow(id, opts)KlaviyoAPI::Flows.get_flow_action_messages(id, opts)KlaviyoAPI::Flows.get_flow_action_relationships_flow(id)KlaviyoAPI::Flows.get_flow_action_relationships_messages(id, opts)KlaviyoAPI::Flows.get_flow_flow_actions(id, opts)KlaviyoAPI::Flows.get_flow_message(id, opts)KlaviyoAPI::Flows.get_flow_message_action(id, opts)KlaviyoAPI::Flows.get_flow_message_relationships_action(id)KlaviyoAPI::Flows.get_flow_message_relationships_template(id)KlaviyoAPI::Flows.get_flow_message_template(id, opts)KlaviyoAPI::Flows.get_flow_relationships_flow_actions(id, opts)KlaviyoAPI::Flows.get_flow_relationships_tags(id)KlaviyoAPI::Flows.get_flow_tags(id, opts)KlaviyoAPI::Flows.get_flows(opts)KlaviyoAPI::Flows.update_flow(id, body)KlaviyoAPI::Images.get_image(id, opts)KlaviyoAPI::Images.get_images(opts)KlaviyoAPI::Images.update_image(id, body)KlaviyoAPI::Images.upload_image_from_file(file, opts)KlaviyoAPI::Images.upload_image_from_url(body)KlaviyoAPI::Lists.create_list(body)KlaviyoAPI::Lists.create_list_relationships(id, body)KlaviyoAPI::Lists.delete_list(id)KlaviyoAPI::Lists.delete_list_relationships(id, body)KlaviyoAPI::Lists.get_list(id, opts)KlaviyoAPI::Lists.get_list_profiles(id, opts)KlaviyoAPI::Lists.get_list_relationships_profiles(id, opts)KlaviyoAPI::Lists.get_list_relationships_tags(id)KlaviyoAPI::Lists.get_list_tags(id, opts)KlaviyoAPI::Lists.get_lists(opts)KlaviyoAPI::Lists.update_list(id, body)KlaviyoAPI::Metrics.get_metric(id, opts)KlaviyoAPI::Metrics.get_metrics(opts)KlaviyoAPI::Metrics.query_metric_aggregates(body)KlaviyoAPI::Profiles.create_or_update_profile(body)KlaviyoAPI::Profiles.create_profile(body)KlaviyoAPI::Profiles.create_push_token(body)KlaviyoAPI::Profiles.get_bulk_profile_import_job(job_id, opts)KlaviyoAPI::Profiles.get_bulk_profile_import_job_import_errors(id, opts)KlaviyoAPI::Profiles.get_bulk_profile_import_job_lists(id, opts)KlaviyoAPI::Profiles.get_bulk_profile_import_job_profiles(id, opts)KlaviyoAPI::Profiles.get_bulk_profile_import_job_relationships_lists(id)KlaviyoAPI::Profiles.get_bulk_profile_import_job_relationships_profiles(id, opts)KlaviyoAPI::Profiles.get_bulk_profile_import_jobs(opts)KlaviyoAPI::Profiles.get_profile(id, opts)KlaviyoAPI::Profiles.get_profile_lists(id, opts)KlaviyoAPI::Profiles.get_profile_relationships_lists(id)KlaviyoAPI::Profiles.get_profile_relationships_segments(id)KlaviyoAPI::Profiles.get_profile_segments(id, opts)KlaviyoAPI::Profiles.get_profiles(opts)KlaviyoAPI::Profiles.merge_profiles(body)KlaviyoAPI::Profiles.spawn_bulk_profile_import_job(body)KlaviyoAPI::Profiles.subscribe_profiles(body)KlaviyoAPI::Profiles.suppress_profiles(body)KlaviyoAPI::Profiles.unsubscribe_profiles(body)KlaviyoAPI::Profiles.unsuppress_profiles(body)KlaviyoAPI::Profiles.update_profile(id, body)KlaviyoAPI::Reporting.query_campaign_values(body, opts)KlaviyoAPI::Reporting.query_flow_series(body, opts)KlaviyoAPI::Reporting.query_flow_values(body, opts)KlaviyoAPI::Segments.get_segment(id, opts)KlaviyoAPI::Segments.get_segment_profiles(id, opts)KlaviyoAPI::Segments.get_segment_relationships_profiles(id, opts)KlaviyoAPI::Segments.get_segment_relationships_tags(id)KlaviyoAPI::Segments.get_segment_tags(id, opts)KlaviyoAPI::Segments.get_segments(opts)KlaviyoAPI::Segments.update_segment(id, body)KlaviyoAPI::Tags.create_tag(body)KlaviyoAPI::Tags.create_tag_group(body)KlaviyoAPI::Tags.create_tag_relationships_campaigns(id, body)KlaviyoAPI::Tags.create_tag_relationships_flows(id, body)KlaviyoAPI::Tags.create_tag_relationships_lists(id, body)KlaviyoAPI::Tags.create_tag_relationships_segments(id, body)KlaviyoAPI::Tags.delete_tag(id)KlaviyoAPI::Tags.delete_tag_group(id)KlaviyoAPI::Tags.delete_tag_relationships_campaigns(id, body)KlaviyoAPI::Tags.delete_tag_relationships_flows(id, body)KlaviyoAPI::Tags.delete_tag_relationships_lists(id, body)KlaviyoAPI::Tags.delete_tag_relationships_segments(id, body)KlaviyoAPI::Tags.get_tag(id, opts)KlaviyoAPI::Tags.get_tag_group(id, opts)KlaviyoAPI::Tags.get_tag_group_relationships_tags(id)KlaviyoAPI::Tags.get_tag_group_tags(id, opts)KlaviyoAPI::Tags.get_tag_groups(opts)KlaviyoAPI::Tags.get_tag_relationships_campaigns(id)KlaviyoAPI::Tags.get_tag_relationships_flows(id)KlaviyoAPI::Tags.get_tag_relationships_lists(id)KlaviyoAPI::Tags.get_tag_relationships_segments(id)KlaviyoAPI::Tags.get_tag_relationships_tag_group(id)KlaviyoAPI::Tags.get_tag_tag_group(id, opts)KlaviyoAPI::Tags.get_tags(opts)KlaviyoAPI::Tags.update_tag(id, body)KlaviyoAPI::Tags.update_tag_group(id, body)KlaviyoAPI::Templates.create_template(body)KlaviyoAPI::Templates.create_template_clone(body)KlaviyoAPI::Templates.create_template_render(body)KlaviyoAPI::Templates.delete_template(id)KlaviyoAPI::Templates.get_template(id, opts)KlaviyoAPI::Templates.get_templates(opts)KlaviyoAPI::Templates.update_template(id, body)response = KlaviyoAPI::Catalogs.get_catalog_items({
header_params: {
'Authorization': 'Klaviyo-API-Key your-api-key',
},
debug_auth_names: []
})
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent