Klaviyo-api

Added

- Bulk Create Events API with
- We have added support for creating events in bulk via the EventsApi.bulkCreateEvents method
- Create multiple events for new and existing profiles and/or update profile properties in a single API call. For more information, see our [Events API overview](https://developers.klaviyo.com/en/reference/events_api_overview).

Changed

- Accounts API
- `Accounts.get_account` and `Accounts.get_accounts` have been updated to return the account's locale, e.g. `"en-US"`.

- **Breaking**
- Subscribe API Synchronous Validation Improved
- To provide better feedback for handling SMS subscriptions, we’ve added improved validation behavior to ProfilesApi.subscribeProfiles method. In prior revisions, such requests may appear as 202s but will fail to update SMS consent. To handle this issue, 400 validation errors are returned for the following cases
1. If a profile is subscribed to SMS marketing and [age-gating is enabled](https://help.klaviyo.com/hc/en-us/articles/4408311712667) but age_gated_date_of_birth is not provided, or the DOB does not meet the region's requirements.
2. If the account does not have a sending number in the phone number’s region.
3. If the phone number is in a region not supported by Klaviyo.
4. If consented_at is set and the list or global setting is double opt-in.
- Pydantic V2
- This SDK now uses Pydantic V2. This may cause some compatibility issues if your source code depends on Pydantic V1.
- Renamed Fields in SDK
- As of the 2024-05-15 release, some models fields are named differently than they appear in API documentation. These fields are
- `datetime`: renamed to `datetime_`
- `date`: renamed to `date_`

This is to manage compatibility with Pydantic v2. An example of this can be seen in [StaticScheduleOptions](src/openapi_client/models/static_schedule_options.py).

python
class StaticScheduleOptions(BaseModel):
"""
StaticScheduleOptions
""" noqa: E501
datetime_: datetime = Field(description="The time to send at", alias="datetime")

schedule_options = StaticScheduleOptions(datetime_=datetime.datetime.strptime("2024-05-19T00:00:00+00:00", "%Y-%m-%dT%H:%M:%S%z")
print(schedule_options.datetime_)

Added:

- New `ReportingApi` allows you to request campaign and flow performance data that you can view in the Klaviyo UI.

- `campaign_values_query`
- Request campaign analytics data, for example, a campaign performance report on the open rate over the past 30 days.

- `flow_values_query`
- Request flow analytics data, for example, a flow performance report on the revenue per recipient value over the past 3 months.

- `flow_series_query`
- Fetch flow series data for a specific interval and timeframe, for example, a flow performance report on weekly click rates over the past 12 months.


- New `ProfilesApi` endpoint allows you to create or update a profile with a set of profile attributes.

- `create_or_update_profile`
- This endpoint operates synchronously and offers an upsert pattern similar to the [v1/v2 Identify API](https://developers.klaviyo.com/en/docs/apis_comparison_chart).

Changed:

- Removed the $attribution field from event_properties in get_event and get_events (breaking change).

- To include this data in your request, add include=attributions to your request.

Added

New Endpoints: Bulk Profile Imports

We have added the following endpoints to enable bulk profile imports:
- `Profiles.spawn_bulk_profile_import_job`
- `Profiles.get_bulk_profile_import_job`
- `Profiles.get_bulk_profile_import_jobs`
- `Profiles.get_bulk_profile_import_job_lists`
- `Profiles.get_bulk_profile_import_job_profiles`
- `Profiles.get_bulk_profile_import_job_import_errors`
- `Profiles.get_bulk_profile_import_job_relationships_profiles`
- `Profiles.get_bulk_profile_import_job_relationships_lists`

Changed

Relationships field of `Profiles.subscribe_profiles` payload is now optional

When using `Profiles.subscribe_profiles`, the `relationships` field of the payload is now optional (see [Profiles.subscribe_profiles reference](https://developers.klaviyo.com/en/reference/subscribe_profiles) for details).

Fixed

Patched a bug that was causing query_metric_aggregates to return None upon success

A bug was introduced in version 5.0.0 until this patch, that resulted in this SDK specifically returning None upon success for the following operation [Metrics.query_metrics_aggregates](https://developers.klaviyo.com/en/reference/query_metric_aggregates).

Added

Support for returning list suppressions via the [/profiles endpoint](https://developers.klaviyo.com/en/reference/get_profiles)

We now support filtering on list suppression with the get profiles endpoint, which brings us to parity with v2 list suppression endpoint that was the previously recommended solution.

Rules for suppression [filtering](https://developers.klaviyo.com/en/docs/filtering_):

- You may not mix-and-match list and global filters
- You may only specify a single date filter
- You may or may not specify a reason
- You must specify a list_id to filter on any list suppression properties

Examples:

- To return profiles who were suppressed after a certain date:
`filter="greater-than(subscriptions.email.marketing.suppression.timestamp,2023-03-01T01:00:00Z)"`
- To return profiles who were suppressed from a specific list after a certain date:
`filter="greater-than(subscriptions.email.marketing.list_suppressions.timestamp,2023-03-01T01:00:00Z),equals(subscriptions.email.marketing.list_suppressions.list_id,\"LIST_ID\")"`
- To return all profiles who were suppressed for a specific reason after a certain date:
`filter="greater-than(subscriptions.email.marketing.suppression.timestamp,2023-03-01T01:00:00Z),equals(subscriptions.email.marketing.suppression.reason,\"user_suppressed\")"`

Optionally retrieve subscription status on Get List Profiles, Get Segment Profiles, Get Event Profile

Now you can retrieve subscription status on any endpoint that returns profiles, including Get List Profiles, Get Segment Profiles and Get Event Profile. Use `additional_fields_profile="subscriptions"` on these endpoints to include subscription information.

Changed

Subscription object not returned by default on Get Profile / Get Profiles

The subscription object is no longer returned by default with get profile(s) requests. However, it can be included by adding the `additional_fields_profile="subscriptions"` to the request. This change will allow us to provide a more performant experience when making requests to Get Profiles without including the subscriptions object.

Profile Subscription Fields Renamed

In the interest of providing more clarity and information on the subscription object, we have renamed several fields, and added several as well. This will provide more context on a contact's subscriptions and consent, as well as boolean fields to see who you can or cannot message.

For SMSMarketing:

- `timestamp` is now `consent_timestamp`
- `last_updated` is a new field that mirrors `consent_timestamp`
- `can_receive_sms_marketing` is a new field which is `True` if the profile is consented for SMS

For EmailMarketing:

- `timestamp` is now `consent_timestamp`
- `can_receive_email_marketing` is True if the profile does not have a global suppression
- `suppressions` is now `suppression`
- `last_updated` is a new field that is the most recent of all the dates on the object

Added

- `Images` API
- We now support the following operations to work with images:
- `get_image`
- `get_images`
- `update_image`
- `upload_image_from_file`
- `upload_image_from_url`
- `Coupons` API
- We now support CRUD operations for both Coupons and Coupon Codes
- Check out [Coupons API guide](https://developers.klaviyo.com/en/docs/use_klaviyos_coupons_api) for more information.
- Additional filtering/sorting option for getting profiles from `Lists` and `Segments`: `joined_group_at`
- New profile merge endpoint: `Profiles.merge_profiles`
- Increased the maximum page size limit for `Lists.get_list_relationships_profiles` and `Segments.get_segment_relationships_profiles` to 1000