Whilst every best effort is made to minimise the number of breaking changes, some breaking changes exist to ensure improved method naming conventions and compatibility with OAuth authentication and the v4 API.
This guide is designed to cover changes that developers may need to make to their existing implementation when upgrading to the v2 SDK.
The minimum supported PHP version is 8.0
. Users on older PHP versions should continue to use the v1 SDK.
Authentication is now via OAuth. It's recommended to refer to the README file's Getting Started
section for implementation.
Initializing the ConvertKit_API
class now accepts a clientID
, clientSecret
and accessToken
in place of the existing api_key
and api_secret
:
$api = new \ConvertKit_API\ConvertKit_API(
clientID: '<your_oauth_client_id>',
clientSecret: '<your_oauth_client_secret>',
accessToken: '<your_oauth_access_token>'
);
For list based endpoints which fetch data from the API (such as broadcasts, custom fields, subscribers, tags, email templates, forms, purchases etc.), cursor based pagination is used. The following parameters can be specified in the API methods:
per_page
: Defines the number of results to return, with a maximum value of 100after_cursor
: When specified, returns the next page of results based on the current result'spagination->end_cursor
valuebefore_cursor
: When specified, returns the previous page of results based on the current result'spagination->start_cursor
value
- Added:
get_account_colors()
- Added:
update_account_colors()
- Added:
get_creator_profile()
- Added:
get_email_stats()
- Added:
get_growth_stats()
- Updated:
get_broadcasts()
supports pagination - Updated:
create_broadcast()
:email_layout_template
is nowemail_template_id
. To fetch the ID of the account's email templates, refer toget_email_templates()
preview_text
option addedsubscriber_filter
option added
- Updated:
update_broadcast()
email_layout_template
is nowemail_template_id
. To fetch the ID of the account's email templates, refer toget_email_templates()
preview_text
option addedsubscriber_filter
option added
- Changed:
destroy_broadcast()
is renamed todelete_broadcast()
- Added:
create_custom_fields()
to create multiple custom fields in a single request - Updated:
get_custom_fields()
supports pagination
- Added:
create_subscriber()
. The concept of creating a subscriber via a form, tag or sequence is replaced with this new method. The subscriber can then be subscribed to resources (forms, tag, sequences) as necessary. - Added:
create_subscribers()
to create multiple subscribers in a single request - Added:
get_subscribers()
- Changed:
unsubscribe()
is nowunsubscribe_by_email()
. Useunsubscribe()
for unsubscribing by a subscriber ID - Updated:
get_subscriber_tags()
supports pagination
- Added:
create_tags()
to create multiple tags in a single request - Updated:
get_tags()
supports pagination - Updated:
get_tag_subscriptions()
:- supports pagination
- supports filtering by subscribers by dates, covering
created_after
,created_before
,tagged_after
andtagged_before
sort_order
is no longer supported
- Changed:
tag_subscriber()
is nowtag_subscriber_by_email()
. Usetag_subscriber()
for tagging by subscriber ID
- Added:
get_email_templates()
- Updated:
get_forms()
:- supports pagination
- only returns active forms by default. Use the
status
parameter to filter byactive
,archived
,trashed
orall
- Updated:
get_landing_pages()
:- supports pagination
- only returns active landing pages by default. Use the
status
parameter to filter byactive
,archived
,trashed
orall
- Updated:
get_form_subscriptions()
:- supports pagination
- supports filtering by subscribers by dates, covering
created_after
,created_before
,added_after
andadded_before
sort_order
is no longer supported
- Changed:
add_subscriber_to_form()
is nowadd_subscriber_to_form_by_email()
. Useadd_subscriber_to_form()
for adding subscriber to form by subscriber ID
- Updated:
create_purchase()
now supports named parameters for purchase data, instead of an$options
array - Changed:
list_purchases()
is nowget_purchases()
, with pagination support
- Added:
get_segments()
- Changed:
add_subscriber_to_sequence()
is nowadd_subscriber_to_sequence_by_email()
. Useadd_subscriber_to_sequence()
for adding a subscriber to a sequence by subscriber ID - Updated:
get_sequences()
supports pagination - Updated:
get_sequence_subscriptions()
:- supports pagination
- supports filtering by subscribers by dates, covering
created_after
,created_before
,added_after
andadded_before
sort_order
is no longer supported
- Added:
get_webhooks()
- Changed:
destroy_webhook()
is nowdelete_webhook()
- Removed:
form_subscribe()
was previously deprecated. Useadd_subscriber_to_form()
oradd_subscriber_to_form_by_email()
- Removed:
add_tag()
was previously deprecated. Usetag_subscriber()
ortag_subscriber_by_email()