- SDK version: 1.0.0
- API revision: 2022-10-17
This SDK is a thin wrapper around our API. See our API Reference for full documentation on behavior.
This SDK exactly mirrors the organization and naming convention of the above language-agnostic resources, with a few namespace changes to make it Pythonic (details in Appendix).
This SDK is organized into the following resources:
Catalogs
Client
Events
Flows
Lists
Metrics
Profiles
Segments
Templates
You can install this library using our pip package here.
Depending on your system configuration, you will need to run one of the following shell commands:
pip install klaviyo-apiOR
pip3 install klaviyo-apiNOTE:
- The SDK retries on resolvable errors, namely: rate limits (common) and server errors (rare).
- The keyword arguments define some advanced settings; the example is populated with the default values.
max_delaydenotes total delay (in seconds) across all attempts.
fromklaviyo_apiimportKlaviyoAPIklaviyo=KlaviyoAPI("YOUR API KEY HERE", max_delay=60, max_retries=3, test_host=None)klaviyo.Metrics.get_metrics() This SDK throws an ApiException error when the server returns a non-2XX response.
An ApiException consists of the following attributes:
status:intreason:strbody:bytes- this can be decoded into a native python dictionary as follows:
# to decode to a dictionaryimportjsonBODY_DICT=json.loads(YOUR_EXCEPTION.body) # to decode to a stringBODY_STRING=YOUR_EXCEPTION.body.decode('utf-8')
- this can be decoded into a native python dictionary as follows:
headers: class 'urllib3._collections.HTTPHeaderDict'- This can be interacted with as a normal dictionary:
- ex:
date = YOUR_EXCEPTION.headers['Date'] keys = YOUR_EXCEPTION.headers.keys() values = YOUR_EXCEPTION.headers.values()
- ex:
- This can be interacted with as a normal dictionary:
- The main difference between this SDK and the language-agnostic API Docs that the below endpoints link to is that this SDK automatically adds the
revisionheader corresponding to the SDK version. - Organization: Resource groups and operation_ids are listed below 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 keyword args may potentially be required for the API call to succeed, the linked API docs are the source of truth regarding which keyword params are required.
- JSON payloads should be passed in as native python dictionaries.
- You can override the client private key by passing in an optional
api_keykeyword arg to any API call that takes a private key. As a reminder: do NOT do this client-side/onsite.
## Positional Arguments# body | dictklaviyo.Catalogs.create_catalog_category(body);## Positional Arguments# id | str# related_resource | str# body | dictklaviyo.Catalogs.create_catalog_category_relationships(id, related_resource, body);## Positional Arguments# body | dictklaviyo.Catalogs.create_catalog_item(body);## Positional Arguments# id | str# related_resource | str# body | dictklaviyo.Catalogs.create_catalog_item_relationships(id, related_resource, body);## Positional Arguments# body | dictklaviyo.Catalogs.create_catalog_variant(body);## Positional Arguments# id | strklaviyo.Catalogs.delete_catalog_category(id);## Positional Arguments# id | str# related_resource | str# body | dictklaviyo.Catalogs.delete_catalog_category_relationships(id, related_resource, body);## Positional Arguments# id | strklaviyo.Catalogs.delete_catalog_item(id);## Positional Arguments# id | str# related_resource | str# body | dictklaviyo.Catalogs.delete_catalog_item_relationships(id, related_resource, body);## Positional Arguments# id | strklaviyo.Catalogs.delete_catalog_variant(id);## Keyword Arguments# fields_catalog_category | [str]# filter | str# page_cursor | str# sort | strklaviyo.Catalogs.get_catalog_categories(fields_catalog_category=fields_catalog_category, filter=filter, page_cursor=page_cursor, sort=sort);## Positional Arguments# id | str## Keyword Arguments# fields_catalog_category | [str]klaviyo.Catalogs.get_catalog_category(id, fields_catalog_category=fields_catalog_category);## Positional Arguments# category_id | str## Keyword Arguments# fields_catalog_item | [str]# fields_catalog_variant | [str]# filter | str# include | [str]# page_cursor | str# sort | strklaviyo.Catalogs.get_catalog_category_items(category_id, fields_catalog_item=fields_catalog_item, fields_catalog_variant=fields_catalog_variant, filter=filter, include=include, page_cursor=page_cursor, sort=sort);## Positional Arguments# id | str# related_resource | str## Keyword Arguments# page_cursor | strklaviyo.Catalogs.get_catalog_category_relationships(id, related_resource, page_cursor=page_cursor);## Positional Arguments# id | str## Keyword Arguments# fields_catalog_item | [str]# fields_catalog_variant | [str]# include | [str]klaviyo.Catalogs.get_catalog_item(id, fields_catalog_item=fields_catalog_item, fields_catalog_variant=fields_catalog_variant, include=include);## Positional Arguments# item_id | str## Keyword Arguments# fields_catalog_category | [str]# filter | str# page_cursor | str# sort | strklaviyo.Catalogs.get_catalog_item_categories(item_id, fields_catalog_category=fields_catalog_category, filter=filter, page_cursor=page_cursor, sort=sort);## Positional Arguments# id | str# related_resource | str## Keyword Arguments# page_cursor | strklaviyo.Catalogs.get_catalog_item_relationships(id, related_resource, page_cursor=page_cursor);## Positional Arguments# item_id | str## Keyword Arguments# fields_catalog_variant | [str]# filter | str# page_cursor | str# sort | strklaviyo.Catalogs.get_catalog_item_variants(item_id, fields_catalog_variant=fields_catalog_variant, filter=filter, page_cursor=page_cursor, sort=sort);## Keyword Arguments# fields_catalog_item | [str]# fields_catalog_variant | [str]# filter | str# include | [str]# page_cursor | str# sort | strklaviyo.Catalogs.get_catalog_items(fields_catalog_item=fields_catalog_item, fields_catalog_variant=fields_catalog_variant, filter=filter, include=include, page_cursor=page_cursor, sort=sort);## Positional Arguments# id | str## Keyword Arguments# fields_catalog_variant | [str]klaviyo.Catalogs.get_catalog_variant(id, fields_catalog_variant=fields_catalog_variant);## Keyword Arguments# fields_catalog_variant | [str]# filter | str# page_cursor | str# sort | strklaviyo.Catalogs.get_catalog_variants(fields_catalog_variant=fields_catalog_variant, filter=filter, page_cursor=page_cursor, sort=sort);## Positional Arguments# job_id | str## Keyword Arguments# fields_catalog_category_bulk_create_job | [str]# fields_catalog_category | [str]# include | [str]klaviyo.Catalogs.get_create_categories_job(job_id, fields_catalog_category_bulk_create_job=fields_catalog_category_bulk_create_job, fields_catalog_category=fields_catalog_category, include=include);## Keyword Arguments# fields_catalog_category_bulk_create_job | [str]# filter | str# page_cursor | strklaviyo.Catalogs.get_create_categories_jobs(fields_catalog_category_bulk_create_job=fields_catalog_category_bulk_create_job, filter=filter, page_cursor=page_cursor);## Positional Arguments# job_id | str## Keyword Arguments# fields_catalog_item_bulk_create_job | [str]# fields_catalog_item | [str]# include | [str]klaviyo.Catalogs.get_create_items_job(job_id, fields_catalog_item_bulk_create_job=fields_catalog_item_bulk_create_job, fields_catalog_item=fields_catalog_item, include=include);## Keyword Arguments# fields_catalog_item_bulk_create_job | [str]# filter | str# page_cursor | strklaviyo.Catalogs.get_create_items_jobs(fields_catalog_item_bulk_create_job=fields_catalog_item_bulk_create_job, filter=filter, page_cursor=page_cursor);## Positional Arguments# job_id | str## Keyword Arguments# fields_catalog_variant_bulk_create_job | [str]# fields_catalog_variant | [str]# include | [str]klaviyo.Catalogs.get_create_variants_job(job_id, fields_catalog_variant_bulk_create_job=fields_catalog_variant_bulk_create_job, fields_catalog_variant=fields_catalog_variant, include=include);## Keyword Arguments# fields_catalog_variant_bulk_create_job | [str]# filter | str# page_cursor | strklaviyo.Catalogs.get_create_variants_jobs(fields_catalog_variant_bulk_create_job=fields_catalog_variant_bulk_create_job, filter=filter, page_cursor=page_cursor);## Positional Arguments# job_id | str## Keyword Arguments# fields_catalog_category_bulk_delete_job | [str]klaviyo.Catalogs.get_delete_categories_job(job_id, fields_catalog_category_bulk_delete_job=fields_catalog_category_bulk_delete_job);## Keyword Arguments# fields_catalog_category_bulk_delete_job | [str]# filter | str# page_cursor | strklaviyo.Catalogs.get_delete_categories_jobs(fields_catalog_category_bulk_delete_job=fields_catalog_category_bulk_delete_job, filter=filter, page_cursor=page_cursor);## Positional Arguments# job_id | str## Keyword Arguments# fields_catalog_item_bulk_delete_job | [str]klaviyo.Catalogs.get_delete_items_job(job_id, fields_catalog_item_bulk_delete_job=fields_catalog_item_bulk_delete_job);## Keyword Arguments# fields_catalog_item_bulk_delete_job | [str]# filter | str# page_cursor | strklaviyo.Catalogs.get_delete_items_jobs(fields_catalog_item_bulk_delete_job=fields_catalog_item_bulk_delete_job, filter=filter, page_cursor=page_cursor);## Positional Arguments# job_id | str## Keyword Arguments# fields_catalog_variant_bulk_delete_job | [str]klaviyo.Catalogs.get_delete_variants_job(job_id, fields_catalog_variant_bulk_delete_job=fields_catalog_variant_bulk_delete_job);## Keyword Arguments# fields_catalog_variant_bulk_delete_job | [str]# filter | str# page_cursor | strklaviyo.Catalogs.get_delete_variants_jobs(fields_catalog_variant_bulk_delete_job=fields_catalog_variant_bulk_delete_job, filter=filter, page_cursor=page_cursor);## Positional Arguments# job_id | str## Keyword Arguments# fields_catalog_category_bulk_update_job | [str]# fields_catalog_category | [str]# include | [str]klaviyo.Catalogs.get_update_categories_job(job_id, fields_catalog_category_bulk_update_job=fields_catalog_category_bulk_update_job, fields_catalog_category=fields_catalog_category, include=include);## Keyword Arguments# fields_catalog_category_bulk_update_job | [str]# filter | str# page_cursor | strklaviyo.Catalogs.get_update_categories_jobs(fields_catalog_category_bulk_update_job=fields_catalog_category_bulk_update_job, filter=filter, page_cursor=page_cursor);## Positional Arguments# job_id | str## Keyword Arguments# fields_catalog_item_bulk_update_job | [str]# fields_catalog_item | [str]# include | [str]klaviyo.Catalogs.get_update_items_job(job_id, fields_catalog_item_bulk_update_job=fields_catalog_item_bulk_update_job, fields_catalog_item=fields_catalog_item, include=include);## Keyword Arguments# fields_catalog_item_bulk_update_job | [str]# filter | str# page_cursor | strklaviyo.Catalogs.get_update_items_jobs(fields_catalog_item_bulk_update_job=fields_catalog_item_bulk_update_job, filter=filter, page_cursor=page_cursor);## Positional Arguments# job_id | str## Keyword Arguments# fields_catalog_variant_bulk_update_job | [str]# fields_catalog_variant | [str]# include | [str]klaviyo.Catalogs.get_update_variants_job(job_id, fields_catalog_variant_bulk_update_job=fields_catalog_variant_bulk_update_job, fields_catalog_variant=fields_catalog_variant, include=include);## Keyword Arguments# fields_catalog_variant_bulk_update_job | [str]# filter | str# page_cursor | strklaviyo.Catalogs.get_update_variants_jobs(fields_catalog_variant_bulk_update_job=fields_catalog_variant_bulk_update_job, filter=filter, page_cursor=page_cursor);## Positional Arguments# body | dictklaviyo.Catalogs.spawn_create_categories_job(body);## Positional Arguments# body | dictklaviyo.Catalogs.spawn_create_items_job(body);## Positional Arguments# body | dictklaviyo.Catalogs.spawn_create_variants_job(body);## Positional Arguments# body | dictklaviyo.Catalogs.spawn_delete_categories_job(body);## Positional Arguments# body | dictklaviyo.Catalogs.spawn_delete_items_job(body);## Positional Arguments# body | dictklaviyo.Catalogs.spawn_delete_variants_job(body);## Positional Arguments# body | dictklaviyo.Catalogs.spawn_update_categories_job(body);## Positional Arguments# body | dictklaviyo.Catalogs.spawn_update_items_job(body);## Positional Arguments# body | dictklaviyo.Catalogs.spawn_update_variants_job(body);## Positional Arguments# id | str# body | dictklaviyo.Catalogs.update_catalog_category(id, body);## Positional Arguments# id | str# related_resource | str# body | dictklaviyo.Catalogs.update_catalog_category_relationships(id, related_resource, body);## Positional Arguments# id | str# body | dictklaviyo.Catalogs.update_catalog_item(id, body);## Positional Arguments# id | str# related_resource | str# body | dictklaviyo.Catalogs.update_catalog_item_relationships(id, related_resource, body);## Positional Arguments# id | str# body | dictklaviyo.Catalogs.update_catalog_variant(id, body);## Positional Arguments# company_id | str# body | dictklaviyo.Client.create_client_event(company_id, body);## Positional Arguments# company_id | str# body | dictklaviyo.Client.create_client_profile(company_id, body);## Positional Arguments# company_id | str# body | dictklaviyo.Client.create_client_subscription(company_id, body);## Positional Arguments# body | dictklaviyo.Events.create_event(body);## Positional Arguments# id | str## Keyword Arguments# fields_event | [str]# fields_metric | [str]# fields_profile | [str]# include | [str]klaviyo.Events.get_event(id, fields_event=fields_event, fields_metric=fields_metric, fields_profile=fields_profile, include=include);## Positional Arguments# id | str## Keyword Arguments# fields_metric | [str]klaviyo.Events.get_event_metrics(id, fields_metric=fields_metric);## Positional Arguments# id | str## Keyword Arguments# fields_profile | [str]klaviyo.Events.get_event_profiles(id, fields_profile=fields_profile);## Positional Arguments# id | str# related_resource | strklaviyo.Events.get_event_relationships(id, related_resource);## Keyword Arguments# fields_event | [str]# fields_metric | [str]# fields_profile | [str]# filter | str# include | [str]# page_cursor | str# sort | strklaviyo.Events.get_events(fields_event=fields_event, fields_metric=fields_metric, fields_profile=fields_profile, filter=filter, include=include, page_cursor=page_cursor, sort=sort);## Positional Arguments# id | str## Keyword Arguments# fields_flow_action | [str]# fields_flow | [str]# include | [str]klaviyo.Flows.get_flow(id, fields_flow_action=fields_flow_action, fields_flow=fields_flow, include=include);## Positional Arguments# id | str## Keyword Arguments# fields_flow_action | [str]# fields_flow_message | [str]# fields_flow | [str]# include | [str]klaviyo.Flows.get_flow_action(id, fields_flow_action=fields_flow_action, fields_flow_message=fields_flow_message, fields_flow=fields_flow, include=include);## Positional Arguments# action_id | str## Keyword Arguments# fields_flow | [str]klaviyo.Flows.get_flow_action_flow(action_id, fields_flow=fields_flow);## Positional Arguments# action_id | str## Keyword Arguments# fields_flow_message | [str]# filter | str# sort | strklaviyo.Flows.get_flow_action_messages(action_id, fields_flow_message=fields_flow_message, filter=filter, sort=sort);## Positional Arguments# id | str# related_resource | str## Keyword Arguments# filter | str# sort | strklaviyo.Flows.get_flow_action_relationships(id, related_resource, filter=filter, sort=sort);## Positional Arguments# flow_id | str## Keyword Arguments# fields_flow_action | [str]# filter | str# sort | strklaviyo.Flows.get_flow_flow_actions(flow_id, fields_flow_action=fields_flow_action, filter=filter, sort=sort);## Positional Arguments# id | str## Keyword Arguments# fields_flow_action | [str]# fields_flow_message | [str]# include | [str]klaviyo.Flows.get_flow_message(id, fields_flow_action=fields_flow_action, fields_flow_message=fields_flow_message, include=include);## Positional Arguments# message_id | str## Keyword Arguments# fields_flow_action | [str]klaviyo.Flows.get_flow_message_action(message_id, fields_flow_action=fields_flow_action);## Positional Arguments# id | str# related_resource | strklaviyo.Flows.get_flow_message_relationships(id, related_resource);## Positional Arguments# id | str# related_resource | str## Keyword Arguments# filter | str# sort | strklaviyo.Flows.get_flow_relationships(id, related_resource, filter=filter, sort=sort);## Keyword Arguments# fields_flow_action | [str]# fields_flow | [str]# filter | str# include | [str]# sort | strklaviyo.Flows.get_flows(fields_flow_action=fields_flow_action, fields_flow=fields_flow, filter=filter, include=include, sort=sort);## Positional Arguments# id | str# body | dictklaviyo.Flows.update_flow(id, body);## Positional Arguments# body | dictklaviyo.Lists.create_list(body);## Positional Arguments# id | str# related_resource | str# body | dictklaviyo.Lists.create_list_relationships(id, related_resource, body);## Positional Arguments# id | strklaviyo.Lists.delete_list(id);## Positional Arguments# id | str# related_resource | str# body | dictklaviyo.Lists.delete_list_relationships(id, related_resource, body);## Positional Arguments# id | str## Keyword Arguments# fields_list | [str]klaviyo.Lists.get_list(id, fields_list=fields_list);## Positional Arguments# list_id | str## Keyword Arguments# fields_profile | [str]# filter | str# page_cursor | strklaviyo.Lists.get_list_profiles(list_id, fields_profile=fields_profile, filter=filter, page_cursor=page_cursor);## Positional Arguments# id | str# related_resource | str## Keyword Arguments# page_cursor | strklaviyo.Lists.get_list_relationships(id, related_resource, page_cursor=page_cursor);## Keyword Arguments# fields_list | [str]# filter | str# page_cursor | strklaviyo.Lists.get_lists(fields_list=fields_list, filter=filter, page_cursor=page_cursor);## Positional Arguments# id | str# body | dictklaviyo.Lists.update_list(id, body);## Positional Arguments# id | str## Keyword Arguments# fields_metric | [str]klaviyo.Metrics.get_metric(id, fields_metric=fields_metric);## Keyword Arguments# fields_metric | [str]# filter | str# page_cursor | strklaviyo.Metrics.get_metrics(fields_metric=fields_metric, filter=filter, page_cursor=page_cursor);## Positional Arguments# body | dictklaviyo.Metrics.query_metric_aggregates(body);## Positional Arguments# body | dictklaviyo.Profiles.create_profile(body);## Positional Arguments# id | str## Keyword Arguments# fields_list | [str]# fields_profile | [str]# fields_segment | [str]# include | [str]klaviyo.Profiles.get_profile(id, fields_list=fields_list, fields_profile=fields_profile, fields_segment=fields_segment, include=include);## Positional Arguments# profile_id | str## Keyword Arguments# fields_list | [str]klaviyo.Profiles.get_profile_lists(profile_id, fields_list=fields_list);## Positional Arguments# id | str# related_resource | strklaviyo.Profiles.get_profile_relationships(id, related_resource);## Positional Arguments# profile_id | str## Keyword Arguments# fields_segment | [str]klaviyo.Profiles.get_profile_segments(profile_id, fields_segment=fields_segment);## Keyword Arguments# fields_profile | [str]# filter | str# page_cursor | str# sort | strklaviyo.Profiles.get_profiles(fields_profile=fields_profile, filter=filter, page_cursor=page_cursor, sort=sort);## Positional Arguments# body | dictklaviyo.Profiles.subscribe_profiles(body);## Positional Arguments# body | dictklaviyo.Profiles.suppress_profiles(body);## Positional Arguments# body | dictklaviyo.Profiles.unsubscribe_profiles(body);## Positional Arguments# body | dictklaviyo.Profiles.unsuppress_profiles(body);## Positional Arguments# id | str# body | dictklaviyo.Profiles.update_profile(id, body);## Positional Arguments# id | str## Keyword Arguments# fields_segment | [str]klaviyo.Segments.get_segment(id, fields_segment=fields_segment);## Positional Arguments# segment_id | str## Keyword Arguments# filter | str# page_cursor | strklaviyo.Segments.get_segment_profiles(segment_id, filter=filter, page_cursor=page_cursor);## Positional Arguments# id | str# related_resource | str## Keyword Arguments# page_cursor | strklaviyo.Segments.get_segment_relationships(id, related_resource, page_cursor=page_cursor);## Keyword Arguments# fields_segment | [str]# filter | str# page_cursor | strklaviyo.Segments.get_segments(fields_segment=fields_segment, filter=filter, page_cursor=page_cursor);## Positional Arguments# id | str# body | dictklaviyo.Segments.update_segment(id, body);## Positional Arguments# body | dictklaviyo.Templates.create_template(body);## Positional Arguments# id | str# body | dictklaviyo.Templates.create_template_clone(id, body);## Positional Arguments# id | str# body | dictklaviyo.Templates.create_template_render(id, body);## Positional Arguments# id | strklaviyo.Templates.delete_template(id);## Positional Arguments# id | str## Keyword Arguments# fields_template | [str]klaviyo.Templates.get_template(id, fields_template=fields_template);## Keyword Arguments# fields_template | [str]# filter | str# page_cursor | str# sort | strklaviyo.Templates.get_templates(fields_template=fields_template, filter=filter, page_cursor=page_cursor, sort=sort);## Positional Arguments# id | str# body | dictklaviyo.Templates.update_template(id, body);NOTE: These are arguments that you can apply to any endpoint call, and which are unique to the SDK
We currently support the following global keyword args:
api_key: use this to override the client-level api_key which you define upon client instantiation
try:
YOUR_CALLexceptExceptionase:
print(e.status)
print(e.reason)
print(e.body)
print(e.headers)The parameters follow the same naming conventions as the resource groups and operations.
We stick to the following convention for parameters/arguments
- All parameters are passed as function args.
- All query and path params that are tagged as
requiredin the docs are passed as positional args. - All optional query params are passed as keyword args.
- Where applicable, the
bodyparam is passed in as a positional arg, and is expected to be a native python dictionary. Within that dictionary, refer to the API docs to see which fields are required/optional, along with valid values. - There is no need to pass in your private
api_keyfor any operations, as it is defined upon client instantiation; public key is still required where applicable. However, you can pass in an optionalapi_keykwarg to override the client private key for a specific call (REMINDER: don't do this client-side).
In the interest of making the SDK Pythonic, we made the following namespace changes relative to the language agnostic resources up top (API Docs, Guides, etc).
- Resource names use Pascal case, (e.g.
Metrics) - function names and parameter names remain unchanged and use snake case (e.g.
get_metrics, andprofile_id)