Kicks Plugin API
Reference for building a WordPress plugin that is sold, licensed and updated through https://services.kicksdigitalmarketing.com. Version 1. This page is also available as plain Markdown at https://services.kicksdigitalmarketing.com/plugin-api.md.
Overview
- Plugins are sold here as subscriptions. A customer who subscribes receives a license key.
- The plugin you build contains a small updater. It sends the license key and the site's URL to one endpoint, and gets back the latest version, a changelog and a download link.
- The license is valid while its Stripe subscription is active or trialing. When the subscription lapses, the endpoint stops offering updates and downloads. The plugin itself keeps working on the customer's site; only updates stop.
- The subscription quantity is the number of sites the license can be used on. A site takes up a slot the first time it checks in.
- Everything here is JSON over HTTPS. No API key or account is needed: the license key is the credential.
Quick reference
| What | Method and URL | Auth |
|---|---|---|
| Check for updates | POST https://services.kicksdigitalmarketing.com/wp-json/kicks/v1/plugin/update-check | license_key parameter |
| Download the plugin zip | GET https://services.kicksdigitalmarketing.com/kd-plugin-download/ | license key and site URL |
Both endpoints are rate limited per IP address. See Limits and caching.
License keys
- Format:
KD-XXXX-XXXX-XXXX-XXXX, where each X is a hexadecimal character (0-9, A-F). - One key per purchased plugin. A plugin and its add-ons each have their own key.
- Treat the key as a secret. Never log it, never put it in a URL you display, and never ship one inside the plugin zip.
- The customer finds their key in their account, and pastes it into your plugin's settings screen. Your plugin stores it (for example with
update_option) and sends it with every check.
Check for updates
POST https://services.kicksdigitalmarketing.com/wp-json/kicks/v1/plugin/update-check
Send the parameters as a form body (application/x-www-form-urlencoded) or JSON. POST is preferred so the key is not written to access logs. GET with query parameters is also accepted.
| Parameter | Required | Description |
|---|---|---|
| license_key | yes | The customer's key. |
| site_url | yes | The site's home URL, for example https://example.com. Only the host is kept. The first check from a new host uses up one site slot. |
| version | no | The version currently installed. If sent, the response includes update_available. |
Request
curl -X POST "https://services.kicksdigitalmarketing.com/wp-json/kicks/v1/plugin/update-check" \
-d "license_key=KD-0000-0000-0000-0000" \
-d "site_url=https://example.com" \
-d "version=1.2.0"Success response
HTTP 200. success is true.
{
"success": true,
"slug": "kicks-auto-blog",
"plugin_name": "Kicks Auto-Blog",
"version": "1.3.0",
"download_url": "https://services.kicksdigitalmarketing.com/kd-plugin-download/?license_key=KD-0000-0000-0000-0000&site_url=https%3A%2F%2Fexample.com",
"changelog": "<p>Fixed scheduling bug.</p>",
"requires": "6.0",
"tested": "6.6",
"update_available": true
}| Field | Description |
|---|---|
| slug | The plugin's identifier on this site. For an add-on it has the form parent-slug/addon-slug. Do not use it as a folder name. |
| plugin_name | Display name. |
| version | The latest released version. Compare it with the installed version using version_compare(). |
| download_url | Where to fetch the zip. Valid for this license and site only. Always use the URL as returned. |
| changelog | HTML. May be empty. Sanitise before output. |
| requires | Minimum WordPress version. May be empty. |
| tested | Highest WordPress version tested. May be empty. |
| update_available | Present only when you sent version. true when the latest version is higher. |
The response can contain extra fields for particular plugins. Ignore any field you do not recognise.
Feature add-ons
Some add-ons unlock features in a parent plugin and have no file of their own. For these the response has "is_addon": true, and version, download_url, changelog, requires and tested are null. The license is still valid. Skip the update handling and use the response as confirmation that the add-on is active.
{
"success": true,
"is_addon": true,
"slug": "kicks-auto-blog/kicks-auto-blog-managed-posting",
"plugin_name": "Managed Posting",
"version": null,
"download_url": null,
"message": "This license is for a feature addon with no installable file — nothing to update."
}Error response
HTTP 200 for license problems, with success set to false. Branch on error, never on message.
{
"success": false,
"error": "kd_subscription_inactive",
"message": "The subscription for this license is not active."
}| error | Meaning | What the plugin should do |
|---|---|---|
| kd_license_invalid | The key is missing, unknown, or not a plugin license. | Ask the customer to re-enter their key. |
| kd_subscription_inactive | The subscription is cancelled, unpaid or expired. | Tell the customer updates stopped and link them to renew. Keep running. |
| kd_subscription_not_found | The subscription could not be verified right now. | Try again later. Do not treat as expired. |
| kd_domain_limit_reached | The license is already used on the maximum number of sites. | Tell the customer to remove a site in their account, or add a seat. |
| kd_rate_limited | Too many requests (HTTP 429). | Wait for the Retry-After header, in seconds. |
Download
GET https://services.kicksdigitalmarketing.com/kd-plugin-download/
Use the download_url from the update-check response. WordPress's own upgrader can fetch it directly.
You can also call the endpoint yourself and send the credentials as headers, which keeps them out of logs:
curl -L "https://services.kicksdigitalmarketing.com/kd-plugin-download/" \
-H "X-KD-License-Key: KD-0000-0000-0000-0000" \
-H "X-KD-Site-URL: https://example.com" \
-o plugin.zip| Status | Meaning |
|---|---|
| 200 | The zip file is the response body. |
| 400 | The license is for a feature add-on, which has no file. |
| 403 | The license is not valid for download. The body is a short message. |
| 404 | No file has been uploaded for this plugin yet. |
| 429 | Rate limited. See the Retry-After header. |
The license is checked again on every download. A link does not keep working after the subscription ends.
Plugin requirements
- A normal WordPress plugin zip: one top-level folder, containing the main PHP file with a standard plugin header.
- The
Version:in the plugin header must equal the version entered for the plugin on this site. If the header is lower than the listed version, WordPress offers an update that never clears. - Use semantic version numbers (
1.4.2). Updates are offered when the listed version is higher than the installed one. - The folder name inside the zip should stay the same from release to release, or WordPress will install each release alongside the last.
- Do not embed license keys, API secrets or the Stripe secret key in the zip.
Limits and caching
update-check: 60 requests per 10 minutes per IP address.kd-plugin-download: 20 requests per 10 minutes per IP address.- The subscription status is cached on the server for up to 5 minutes. A renewal or cancellation can take that long to show.
- Check at most twice a day. Cache the response with a transient for 12 hours, and cache failures for an hour so a broken response does not cause repeated calls.
- Never check on every admin page load.
Reference updater
A complete drop-in class. Include it in your plugin, and create it once from the main plugin file. The plugin must provide a settings field that saves the license key into the option named in the constructor.
class Kicks_Plugin_Updater {
const API = 'https://services.kicksdigitalmarketing.com/wp-json/kicks/v1/plugin/update-check';
private $basename;
private $slug;
private $key_option;
private $version;
/**
* @param string $plugin_file Pass __FILE__ from the main plugin file.
* @param string $slug Unique string, used for cache keys and plugin info.
* @param string $key_option Name of the option that holds the license key.
*/
public function __construct( $plugin_file, $slug, $key_option ) {
$this->basename = plugin_basename( $plugin_file );
$this->slug = $slug;
$this->key_option = $key_option;
$data = get_file_data( $plugin_file, array( 'Version' => 'Version' ) );
$this->version = $data['Version'];
add_filter( 'pre_set_site_transient_update_plugins', array( $this, 'inject_update' ) );
add_filter( 'plugins_api', array( $this, 'plugin_info' ), 10, 3 );
}
private function check() {
$cache_key = 'kd_upd_' . $this->slug;
$cached = get_site_transient( $cache_key );
if ( false !== $cached ) {
return $cached;
}
$license_key = get_option( $this->key_option );
if ( ! $license_key ) {
return null;
}
$response = wp_remote_post( self::API, array(
'timeout' => 15,
'body' => array(
'license_key' => $license_key,
'site_url' => home_url(),
'version' => $this->version,
),
) );
$data = null;
if ( ! is_wp_error( $response ) && 200 === wp_remote_retrieve_response_code( $response ) ) {
$data = json_decode( wp_remote_retrieve_body( $response ), true );
}
if ( ! is_array( $data ) ) {
set_site_transient( $cache_key, array( 'success' => false ), HOUR_IN_SECONDS );
return null;
}
set_site_transient( $cache_key, $data, 12 * HOUR_IN_SECONDS );
return $data;
}
public function inject_update( $transient ) {
if ( empty( $transient->checked ) ) {
return $transient;
}
$data = $this->check();
if ( $data && ! empty( $data['success'] ) && ! empty( $data['update_available'] ) && ! empty( $data['download_url'] ) ) {
$transient->response[ $this->basename ] = (object) array(
'slug' => $this->slug,
'plugin' => $this->basename,
'new_version' => $data['version'],
'package' => $data['download_url'],
'requires' => $data['requires'] ?? '',
'tested' => $data['tested'] ?? '',
);
}
return $transient;
}
public function plugin_info( $result, $action, $args ) {
if ( 'plugin_information' !== $action || empty( $args->slug ) || $this->slug !== $args->slug ) {
return $result;
}
$data = $this->check();
if ( ! $data || empty( $data['success'] ) ) {
return $result;
}
return (object) array(
'name' => $data['plugin_name'],
'slug' => $this->slug,
'version' => $data['version'],
'requires' => $data['requires'] ?? '',
'tested' => $data['tested'] ?? '',
'sections' => array( 'changelog' => wp_kses_post( $data['changelog'] ?? '' ) ),
);
}
}
// In the main plugin file:
new Kicks_Plugin_Updater( __FILE__, 'my-plugin-slug', 'my_plugin_license_key' );To show the customer why updates stopped, read the error field from the same response and display a notice for kd_subscription_inactive or kd_domain_limit_reached.
Listing a plugin
Only Kicks can publish plugins on this site, so you cannot upload directly. To have a plugin listed:
- Build it to the requirements above, with the updater included.
- Send the zip, a short description, the version, the minimum and tested WordPress versions, and your proposed subscription pricing, to hello@kicksdigital.com.
- Every submission is reviewed by hand, including the code, before it is listed. Plugins run on customers' sites, so expect questions.
Notes for AI assistants
If you are an AI assistant asked to add Kicks licensing and updates to a plugin, follow these steps:
- Copy the reference updater above into the plugin without changing its behaviour. Change only the slug, the option name and the version handling if the plugin already has its own.
- Add a settings field where the customer pastes the license key, stored in the option name you passed to the class. Mask the saved value when it is displayed.
- Make the plugin header
Version:match the version the site owner has listed. - Use only the two endpoints on this page, over HTTPS, with POST for the update check.
- Never hard-code a license key, and never call any other URL on this domain. Endpoints not listed here are private and may change without notice.
- Cache every response as described under Limits and caching. Do not call the API on each page load.
- Treat all response fields as untrusted input. Escape or sanitise before output, and ignore unknown fields.
- Handle every
errorvalue listed above, and keep the plugin working when the license is inactive.