Releases: ConvertKit/convertkit-wordpress-libraries
2.0.4
2.0.3
2.0.2
2.0.1
2.0.0
Version 2.0 of the SDK uses ConvertKit's v4 API, which replaces API Keys with OAuth, and introduces a number of new methods.
As such, this introduces a number of breaking changes.
Class Names
To permit compatibility with WordPress Plugins that may use the v3 API Libraries (1.4.2 or lower), class names are appended with _V4:
ConvertKit_API_V4ConvertKit_Resource_V4
Authentication
Authentication is now via OAuth using PKCE.
Initializing the ConvertKit_API_V4 class now accepts a client_id, redirect_uri, access_token and refresh_token in place of the existing api_key and api_secret:
$api = new ConvertKit_API_V4( 'client_id', 'redirect_uri', 'access_token', 'refresh_token' );The redirect URI must be one listed in the OAuth application.
To obtain an OAuth URL to begin the OAuth flow, the access_token and refresh_token constructor parameters are not required:
$api = new ConvertKit_API_V4( 'client_id', 'redirect_uri' );
$url = $api->get_oauth_url();Once complete, the user is returned to the redirect_uri with a code, which can be used to obtain access and refresh tokens:
$result = $api->get_access_token( 'authorization_code' );Remember to re-initialize the API class with your access and refresh tokens after receiving them.
Refreshing tokens will be attempted automatically by the libraries, if a request is made with an expired access token and a valid refresh token. Your plugin can hook to the convertkit_api_refresh_token WordPress action to listen for changes when this occurs, updating the stored access and refresh tokens in your Plugin accordingly.
Refreshing a token can be performed manually:
$result = $api->refresh_token();Traits
This library inherits the PHP SDK v4 API Traits. Refer to the PHP SDK documentation.
Library-specific methods
To maintain backward compatibility with our WordPress Plugins and the v3 API (1.4.2 and earlier of the WordPress Libraries), a number of methods exist in the ConvertKit_API_V4 class, such as form_subscribe and tag_subscribe.
These may be deprecated in future updates in favour of direct calls to the methods in the traits file.
Pagination
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_cursorvaluebefore_cursor: When specified, returns the previous page of results based on the current result'spagination->start_cursorvalue
Accounts
- Added:
get_account_colors() - Added:
update_account_colors() - Added:
get_creator_profile() - Added:
get_email_stats() - Added:
get_growth_stats()
Broadcasts
- Updated:
get_broadcasts()supports pagination - Updated:
create_broadcast():email_layout_templateis nowemail_template_id. To fetch the ID of the account's email templates, refer toget_email_templates()preview_textoption addedsubscriber_filteroption added
- Updated:
update_broadcast()email_layout_templateis nowemail_template_id. To fetch the ID of the account's email templates, refer toget_email_templates()preview_textoption addedsubscriber_filteroption added
- Changed:
destroy_broadcast()is renamed todelete_broadcast()
Custom Fields
- Added:
create_custom_fields()to create multiple custom fields in a single request - Updated:
get_custom_fields()supports pagination
Subscribers
- 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
Tags
- 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_afterandtagged_before sort_orderis no longer supported
- Changed:
tag_subscriber()is nowtag_subscriber_by_email(). Usetag_subscriber()for tagging by subscriber ID
Email Templates
- Added:
get_email_templates()
Forms
- Updated:
get_forms():- supports pagination
- only returns active forms by default. Use the
statusparameter to filter byactive,archived,trashedorall
- Updated:
get_landing_pages():- supports pagination
- only returns active landing pages by default. Use the
statusparameter to filter byactive,archived,trashedorall
- Updated:
get_form_subscriptions():- supports pagination
- supports filtering by subscribers by dates, covering
created_after,created_before,added_afterandadded_before sort_orderis 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
Purchases
- Updated:
create_purchase()now supports named parameters for purchase data, instead of an$optionsarray - Changed:
list_purchases()is nowget_purchases(), with pagination support
Segments
- Added:
get_segments()
Sequences
- 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_afterandadded_before sort_orderis no longer supported
Webhooks
- Added:
get_webhooks() - Changed:
destroy_webhook()is nowdelete_webhook()
Other
- 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()