Merge pull request #22 from klaviyo/readme-examples

Added readme examples

Author: jon-batscha

README.md

@@ -1,6 +1,6 @@
 # Klaviyo Python SDK
 
-- SDK version: 2.0.1
+- SDK version: 2.0.2
 - API revision: 2023-02-22
 
 ## Helpful Resources
@@ -107,6 +107,73 @@ klaviyo = KlaviyoAPI("YOUR API KEY HERE", max_delay=60, max_retries=3, test_host
 klaviyo.Metrics.get_metrics() 
 ```
 
+### Use Case Examples
+
+#### How to use filtering, sorting, and spare fieldset JSON API features
+
+**Use Case**: Get events associated with a specific metric, then return just the event properties sorted by oldest to newest datetime.
+
+```python
+klaviyo.Events.get_events(
+    fields_event=['event_properties'], 
+    filter="equals(metric_id,\"aBc123\")", 
+    sort='-datetime'
+    )
+```
+
+NOTE: the filter param values need to be url-encoded
+
+#### How to filter based on datetime
+
+**Use Case**: Get profiles that have been updated between two datetimes.
+
+```python
+klaviyo.Profiles.get_profiles(
+    filter='less-than(updated,2023-04-26T00:00:00Z),greater-than(updated,2023-04-19T00:00:00Z)'
+    )
+```
+
+#### How to use pagination and the page[size] param
+
+**Use Case**: Use cursor-based pagination to get the next 20 profile records.
+
+```python
+klaviyo.Profiles.get_profiles(
+    page_cursor="https://a.klaviyo.com/api/profiles/?page%5Bcursor%5D=bmV4dDo6aWQ6OjAxRjNaWk5ITlRYMUtFVEhQMzJTUzRBN0ZY",
+    page_size=20
+)
+```
+
+NOTE: This page cursor value is exactly what is returned in the `self`/`next`/`prev` response values
+
+#### How to add additional information to your API response via additional-fields and the `includes` parameter
+
+**Use Case**: Get a specific profile, return an additional predictive analytics field, and also return the list objects associated with the profile.
+
+```python
+klaviyo.Profiles.get_profile(
+    '01GDDKASAP8TKDDA2GRZDSVP4H', 
+    additional_fields_profile=['predictive_analytics'], 
+    include=['lists']
+)
+```
+
+#### How to use our relationship endpoints to see related resources
+
+**Use Case**: Get all list memberships for a profile with the given `profile_id`.
+
+```python
+klaviyo.Profiles.get_profile_relationships_lists('01GDDKASAP8TKDDA2GRZDSVP4H')
+```
+
+#### How to see what Klaviyo objects are associated with a specific tag
+
+**Use Case**: Get all campaigns associated with the given `tag_id`.
+
+```python
+klaviyo.Tags.get_tag_relationships_campaigns('9c8db7a0-5ab5-4e3c-9a37-a3224fd14382')
+```
+
 ## Error Handling
 
 This SDK throws an `ApiException` error when the server returns a non-`2XX` response. 
@@ -1496,9 +1563,10 @@ klaviyo.Flows.get_flow_action_flow(action_id, fields_flow=fields_flow)
 # fields_flow_message | [str]
 # filter | str
 # page_cursor | str
+# page_size | int
 # sort | str
 
-klaviyo.Flows.get_flow_action_messages(action_id, fields_flow_message=fields_flow_message, filter=filter, page_cursor=page_cursor, sort=sort)
+klaviyo.Flows.get_flow_action_messages(action_id, fields_flow_message=fields_flow_message, filter=filter, page_cursor=page_cursor, page_size=page_size, sort=sort)
 ```
 
 
@@ -1528,9 +1596,10 @@ klaviyo.Flows.get_flow_action_relationships_flow(id)
 
 # filter | str
 # page_cursor | str
+# page_size | int
 # sort | str
 
-klaviyo.Flows.get_flow_action_relationships_messages(id, filter=filter, page_cursor=page_cursor, sort=sort)
+klaviyo.Flows.get_flow_action_relationships_messages(id, filter=filter, page_cursor=page_cursor, page_size=page_size, sort=sort)
 ```
 
 
@@ -1548,9 +1617,10 @@ klaviyo.Flows.get_flow_action_relationships_messages(id, filter=filter, page_cur
 # fields_flow_action | [str]
 # filter | str
 # page_cursor | str
+# page_size | int
 # sort | str
 
-klaviyo.Flows.get_flow_flow_actions(flow_id, fields_flow_action=fields_flow_action, filter=filter, page_cursor=page_cursor, sort=sort)
+klaviyo.Flows.get_flow_flow_actions(flow_id, fields_flow_action=fields_flow_action, filter=filter, page_cursor=page_cursor, page_size=page_size, sort=sort)
 ```
 
 
@@ -1615,9 +1685,10 @@ klaviyo.Flows.get_flow_message_relationships_action(id)
 ## Keyword Arguments
 
 # filter | str
+# page_size | int
 # sort | str
 
-klaviyo.Flows.get_flow_relationships_flow_actions(id, filter=filter, sort=sort)
+klaviyo.Flows.get_flow_relationships_flow_actions(id, filter=filter, page_size=page_size, sort=sort)
 ```
 
 
@@ -1664,9 +1735,10 @@ klaviyo.Flows.get_flow_tags(flow_id, fields_tag=fields_tag)
 # filter | str
 # include | [str]
 # page_cursor | str
+# page_size | int
 # sort | str
 
-klaviyo.Flows.get_flows(fields_flow_action=fields_flow_action, fields_flow=fields_flow, filter=filter, include=include, page_cursor=page_cursor, sort=sort)
+klaviyo.Flows.get_flows(fields_flow_action=fields_flow_action, fields_flow=fields_flow, filter=filter, include=include, page_cursor=page_cursor, page_size=page_size, sort=sort)
 ```
 
 
@@ -1920,11 +1992,7 @@ klaviyo.Metrics.query_metric_aggregates(body)
 
 # body | dict
 
-## Keyword Arguments
-
-# additional_fields_profile | [str]
-
-klaviyo.Profiles.create_profile(body, additional_fields_profile=additional_fields_profile)
+klaviyo.Profiles.create_profile(body)
 ```
 
 
@@ -2021,10 +2089,10 @@ klaviyo.Profiles.get_profile_segments(profile_id, fields_segment=fields_segment)
 # fields_profile | [str]
 # filter | str
 # page_cursor | str
-# sort | str
 # page_size | int
+# sort | str
 
-klaviyo.Profiles.get_profiles(additional_fields_profile=additional_fields_profile, fields_profile=fields_profile, filter=filter, page_cursor=page_cursor, sort=sort, page_size=page_size)
+klaviyo.Profiles.get_profiles(additional_fields_profile=additional_fields_profile, fields_profile=fields_profile, filter=filter, page_cursor=page_cursor, page_size=page_size, sort=sort)
 ```
 
 

klaviyo_api/wrapper.py

@@ -32,18 +32,18 @@ class KlaviyoAPI:
 
     _REVISION = "2023-02-22"
 
+    _STATUS_CODE_CONNECTION_RESET_BY_PEER = 104
     _STATUS_CODE_TOO_MANY_REQUESTS = 429
     _STATUS_CODE_SERVICE_UNAVAILABLE = 503
     _STATUS_CODE_GATEWAY_TIMEOUT = 504
     _STATUS_CODE_A_TIMEOUT_OCCURED = 524
-    _STATUS_CODE_CONNECTION_RESET_BY_PEER = 104
 
     _RETRY_CODES = {
+        _STATUS_CODE_CONNECTION_RESET_BY_PEER,
         _STATUS_CODE_TOO_MANY_REQUESTS,
         _STATUS_CODE_SERVICE_UNAVAILABLE,
         _STATUS_CODE_GATEWAY_TIMEOUT,
         _STATUS_CODE_A_TIMEOUT_OCCURED,
-        _STATUS_CODE_CONNECTION_RESET_BY_PEER
         }
 
     _CURSOR_SEARCH_TOKENS = ['page%5Bcursor%5D','page[cursor]']

openapi_client/__init__.py

@@ -11,7 +11,7 @@
 """
 
 
-__version__ = "2.0.1"
+__version__ = "2.0.2"
 
 # import ApiClient
 from openapi_client.api_client import ApiClient

openapi_client/api/campaigns_api.py

@@ -1158,7 +1158,7 @@ def create_campaign(
     ):
         """Create Campaign  # noqa: E501
 
-        Creates a campaign given a set of parameters, then returns it.<br><br>*Rate limits*:<br>Burst: `10/s`<br>Steady: `150/m`  **Scopes:** `Campaigns Write`  # noqa: E501
+        Creates a campaign given a set of parameters, then returns it.<br><br>*Rate limits*:<br>Burst: `10/s`<br>Steady: `150/m`  **Scopes:** `campaigns:write`  # noqa: E501
         This method makes a synchronous HTTP request by default. To make an
         asynchronous HTTP request, please pass async_req=True
 
@@ -1241,7 +1241,7 @@ def create_campaign_clone(
     ):
         """Create Campaign Clone  # noqa: E501
 
-        Clones an existing campaign, returning a new campaign based on the original with a new ID and name.<br><br>*Rate limits*:<br>Burst: `10/s`<br>Steady: `150/m`  **Scopes:** `Campaigns Write`  # noqa: E501
+        Clones an existing campaign, returning a new campaign based on the original with a new ID and name.<br><br>*Rate limits*:<br>Burst: `10/s`<br>Steady: `150/m`  **Scopes:** `campaigns:write`  # noqa: E501
         This method makes a synchronous HTTP request by default. To make an
         asynchronous HTTP request, please pass async_req=True
 
@@ -1324,7 +1324,7 @@ def create_campaign_message_assign_template(
     ):
         """Assign Campaign Message Template  # noqa: E501
 
-        Creates a non-reusable version of the template and assigns it to the message.<br><br>*Rate limits*:<br>Burst: `10/s`<br>Steady: `150/m`  **Scopes:** `Campaigns Write`  # noqa: E501
+        Creates a non-reusable version of the template and assigns it to the message.<br><br>*Rate limits*:<br>Burst: `10/s`<br>Steady: `150/m`  **Scopes:** `campaigns:write`  # noqa: E501
         This method makes a synchronous HTTP request by default. To make an
         asynchronous HTTP request, please pass async_req=True
 
@@ -1407,7 +1407,7 @@ def create_campaign_recipient_estimation_job(
     ):
         """Create Campaign Recipient Estimation Job  # noqa: E501
 
-        Trigger an asynchronous job to update the estimated number of recipients for the given campaign ID. Use the `Get Campaign Recipient Estimation Job` endpoint to retrieve the status of this estimation job. Use the `Get Campaign Recipient Estimation` endpoint to retrieve the estimated recipient count for a given campaign.<br><br>*Rate limits*:<br>Burst: `10/s`<br>Steady: `150/m`  **Scopes:** `Campaigns Write`  # noqa: E501
+        Trigger an asynchronous job to update the estimated number of recipients for the given campaign ID. Use the `Get Campaign Recipient Estimation Job` endpoint to retrieve the status of this estimation job. Use the `Get Campaign Recipient Estimation` endpoint to retrieve the estimated recipient count for a given campaign.<br><br>*Rate limits*:<br>Burst: `10/s`<br>Steady: `150/m`  **Scopes:** `campaigns:write`  # noqa: E501
         This method makes a synchronous HTTP request by default. To make an
         asynchronous HTTP request, please pass async_req=True
 
@@ -1490,7 +1490,7 @@ def create_campaign_send_job(
     ):
         """Create Campaign Send Job  # noqa: E501
 
-        Trigger a campaign to send asynchronously<br><br>*Rate limits*:<br>Burst: `10/s`<br>Steady: `150/m`  **Scopes:** `Campaigns Write`  # noqa: E501
+        Trigger a campaign to send asynchronously<br><br>*Rate limits*:<br>Burst: `10/s`<br>Steady: `150/m`  **Scopes:** `campaigns:write`  # noqa: E501
         This method makes a synchronous HTTP request by default. To make an
         asynchronous HTTP request, please pass async_req=True
 
@@ -1573,7 +1573,7 @@ def delete_campaign(
     ):
         """Delete Campaign  # noqa: E501
 
-        Delete a campaign with the given campaign ID.<br><br>*Rate limits*:<br>Burst: `10/s`<br>Steady: `150/m`  **Scopes:** `Campaigns Write`  # noqa: E501
+        Delete a campaign with the given campaign ID.<br><br>*Rate limits*:<br>Burst: `10/s`<br>Steady: `150/m`  **Scopes:** `campaigns:write`  # noqa: E501
         This method makes a synchronous HTTP request by default. To make an
         asynchronous HTTP request, please pass async_req=True
 
@@ -1656,7 +1656,7 @@ def get_campaign(
     ):
         """Get Campaign  # noqa: E501
 
-        Returns a specific campaign based on a required id.<br><br>*Rate limits*:<br>Burst: `10/s`<br>Steady: `150/m`  **Scopes:** `Campaigns Read`  # noqa: E501
+        Returns a specific campaign based on a required id.<br><br>*Rate limits*:<br>Burst: `10/s`<br>Steady: `150/m`  **Scopes:** `campaigns:read`  # noqa: E501
         This method makes a synchronous HTTP request by default. To make an
         asynchronous HTTP request, please pass async_req=True
 
@@ -1742,7 +1742,7 @@ def get_campaign_message(
     ):
         """Get Campaign Message  # noqa: E501
 
-        Returns a specific message based on a required id.<br><br>*Rate limits*:<br>Burst: `10/s`<br>Steady: `150/m`  **Scopes:** `Campaigns Read`  # noqa: E501
+        Returns a specific message based on a required id.<br><br>*Rate limits*:<br>Burst: `10/s`<br>Steady: `150/m`  **Scopes:** `campaigns:read`  # noqa: E501
         This method makes a synchronous HTTP request by default. To make an
         asynchronous HTTP request, please pass async_req=True
 
@@ -1826,7 +1826,7 @@ def get_campaign_recipient_estimation(
     ):
         """Get Campaign Recipient Estimation  # noqa: E501
 
-        Get the estimated recipient count for a campaign with the provided campaign ID. You can refresh this count by using the `Create Campaign Recipient Estimation Job` endpoint.<br><br>*Rate limits*:<br>Burst: `10/s`<br>Steady: `150/m`  **Scopes:** `Campaigns Read`  # noqa: E501
+        Get the estimated recipient count for a campaign with the provided campaign ID. You can refresh this count by using the `Create Campaign Recipient Estimation Job` endpoint.<br><br>*Rate limits*:<br>Burst: `10/s`<br>Steady: `150/m`  **Scopes:** `campaigns:read`  # noqa: E501
         This method makes a synchronous HTTP request by default. To make an
         asynchronous HTTP request, please pass async_req=True
 
@@ -1910,7 +1910,7 @@ def get_campaign_recipient_estimation_job(
     ):
         """Get Campaign Recipient Estimation Job  # noqa: E501
 
-        Retrieve the status of a recipient estimation job triggered with the `Create Campaign Recipient Estimation Job` endpoint.<br><br>*Rate limits*:<br>Burst: `10/s`<br>Steady: `150/m`  **Scopes:** `Campaigns Read`  # noqa: E501
+        Retrieve the status of a recipient estimation job triggered with the `Create Campaign Recipient Estimation Job` endpoint.<br><br>*Rate limits*:<br>Burst: `10/s`<br>Steady: `150/m`  **Scopes:** `campaigns:read`  # noqa: E501
         This method makes a synchronous HTTP request by default. To make an
         asynchronous HTTP request, please pass async_req=True
 
@@ -1994,7 +1994,7 @@ def get_campaign_relationships_tags(
     ):
         """Get Campaign Relationships Tags  # noqa: E501
 
-        Returns the IDs of all tags associated with the given campaign.<br><br>*Rate limits*:<br>Burst: `3/s`<br>Steady: `60/m`  **Scopes:** `Campaigns Read` `Tags Read`  # noqa: E501
+        Returns the IDs of all tags associated with the given campaign.<br><br>*Rate limits*:<br>Burst: `3/s`<br>Steady: `60/m`  **Scopes:** `campaigns:read` `tags:read`  # noqa: E501
         This method makes a synchronous HTTP request by default. To make an
         asynchronous HTTP request, please pass async_req=True
 
@@ -2077,7 +2077,7 @@ def get_campaign_send_job(
     ):
         """Get Campaign Send Job  # noqa: E501
 
-        Get a campaign send job<br><br>*Rate limits*:<br>Burst: `10/s`<br>Steady: `150/m`  **Scopes:** `Campaigns Read`  # noqa: E501
+        Get a campaign send job<br><br>*Rate limits*:<br>Burst: `10/s`<br>Steady: `150/m`  **Scopes:** `campaigns:read`  # noqa: E501
         This method makes a synchronous HTTP request by default. To make an
         asynchronous HTTP request, please pass async_req=True
 
@@ -2161,7 +2161,7 @@ def get_campaign_tags(
     ):
         """Get Campaign Tags  # noqa: E501
 
-        Return all tags that belong to the given campaign.<br><br>*Rate limits*:<br>Burst: `3/s`<br>Steady: `60/m`  **Scopes:** `Campaigns Read` `Tags Read`  # noqa: E501
+        Return all tags that belong to the given campaign.<br><br>*Rate limits*:<br>Burst: `3/s`<br>Steady: `60/m`  **Scopes:** `campaigns:read` `tags:read`  # noqa: E501
         This method makes a synchronous HTTP request by default. To make an
         asynchronous HTTP request, please pass async_req=True
 
@@ -2244,7 +2244,7 @@ def get_campaigns(
     ):
         """Get Campaigns  # noqa: E501
 
-        Returns some or all campaigns based on [optional] filters<br><br>*Rate limits*:<br>Burst: `10/s`<br>Steady: `150/m`  **Scopes:** `Campaigns Read`  # noqa: E501
+        Returns some or all campaigns based on [optional] filters<br><br>*Rate limits*:<br>Burst: `10/s`<br>Steady: `150/m`  **Scopes:** `campaigns:read`  # noqa: E501
         This method makes a synchronous HTTP request by default. To make an
         asynchronous HTTP request, please pass async_req=True
 
@@ -2330,7 +2330,7 @@ def update_campaign(
     ):
         """Update Campaign  # noqa: E501
 
-        Update a campaign with the given campaign ID.<br><br>*Rate limits*:<br>Burst: `10/s`<br>Steady: `150/m`  **Scopes:** `Campaigns Write`  # noqa: E501
+        Update a campaign with the given campaign ID.<br><br>*Rate limits*:<br>Burst: `10/s`<br>Steady: `150/m`  **Scopes:** `campaigns:write`  # noqa: E501
         This method makes a synchronous HTTP request by default. To make an
         asynchronous HTTP request, please pass async_req=True
 
@@ -2417,7 +2417,7 @@ def update_campaign_message(
     ):
         """Update Campaign Message  # noqa: E501
 
-        Update a campaign message<br><br>*Rate limits*:<br>Burst: `10/s`<br>Steady: `150/m`  **Scopes:** `Campaigns Write`  # noqa: E501
+        Update a campaign message<br><br>*Rate limits*:<br>Burst: `10/s`<br>Steady: `150/m`  **Scopes:** `campaigns:write`  # noqa: E501
         This method makes a synchronous HTTP request by default. To make an
         asynchronous HTTP request, please pass async_req=True
 
@@ -2504,7 +2504,7 @@ def update_campaign_send_job(
     ):
         """Update Campaign Send Job  # noqa: E501
 
-        Permanently cancel the campaign, setting the status to CANCELED or revert the campaign, setting the status back to DRAFT<br><br>*Rate limits*:<br>Burst: `10/s`<br>Steady: `150/m`  **Scopes:** `Campaigns Write`  # noqa: E501
+        Permanently cancel the campaign, setting the status to CANCELED or revert the campaign, setting the status back to DRAFT<br><br>*Rate limits*:<br>Burst: `10/s`<br>Steady: `150/m`  **Scopes:** `campaigns:write`  # noqa: E501
         This method makes a synchronous HTTP request by default. To make an
         asynchronous HTTP request, please pass async_req=True