License Manager (API Documentation)

🔍

Overview #

The EasyCommerce License Manager is an addon for EasyCommerce that enables selling licensed products such as WordPress plugins, themes, games, or any software. It provides a REST API for managing licenses, including activation, deactivation, and retrieval of license information.

This API allows developers to integrate license management into their products, enabling automatic license validation and activation tracking.

Base URL #

All API endpoints are prefixed with your WordPress site’s REST API base:

https://your-site.com/wp-json/easycommerce/v1/

Authentication #

For Admin Operations #

• Requires WordPress authentication (logged in as admin)
• Uses WordPress nonce for CSRF protection

For Customer Operations #

• Requires WordPress authentication (logged in as customer)
• Uses WordPress nonce for CSRF protection

For Public Operations (Activation/Deactivation) #

• No authentication required
• License key and email validation used for security

Endpoints #

1. List Licenses #

Retrieve a list of licenses with optional filtering.

Endpoint: GET /wp-json/easycommerce/v1/licenses

Permissions:

• Admin: Can view all licenses
• Customer: Can only view their own licenses

Parameters:

• order_id (integer, optional): Filter by order ID
• customer_id (integer, optional): Filter by customer ID
• status (string, optional): Filter by status (active, inactive, expired, blocked)
• per_page (integer, optional): Number of results per page (default: 10)
• page (integer, optional): Page number (default: 1)

Sample Request:

curl -X GET "https://your-site.com/wp-json/easycommerce/v1/licenses?per_page=5&page=1" \
  -H "X-WP-Nonce: your_nonce_here" \
  -H "Content-Type: application/json"

Sample Response:

{
  "success": true,
  "data": {
    "licenses": [
      {
        "id": 123,
        "key": "ABC123-DEF456-GHI789",
        "order_id": 456,
        "customer_id": 789,
        "customer_name": "John Doe",
        "product_id": 101,
        "product_name": "Premium Plugin",
        "product_variation": "Pro Version",
        "price_id": 1,
        "status": "active",
        "expiry": "2024-12-31 23:59:59",
        "activation_limit": 5,
        "activations": 2
      }
    ],
    "total": 25,
    "per_page": 5,
    "page": 1,
    "total_pages": 5
  }
}

2. Get Single License #

Retrieve detailed information about a specific license.

Endpoint: GET /wp-json/easycommerce/v1/licenses/{key}

Permissions: Customer (can only view their own licenses)

Parameters:

• key (string, required): License ID or license key

Sample Request:

curl -X GET "https://your-site.com/wp-json/easycommerce/v1/licenses/ABC123-DEF456-GHI789" \
  -H "X-WP-Nonce: your_nonce_here" \
  -H "Content-Type: application/json"

Sample Response:

{
  "success": true,
  "data": {
    "id": 123,
    "key": "ABC123-DEF456-GHI789",
    "order_id": 456,
    "customer_id": 789,
    "customer_name": "John Doe",
    "product_id": 101,
    "product_name": "Premium Plugin",
    "price_id": 1,
    "status": "active",
    "expiry": "2024-12-31 23:59:59",
    "activation_limit": 5,
    "activations": [
      {
        "site": "https://example.com",
        "activated_at": "2024-01-15 10:30:00"
      },
      {
        "site": "https://testsite.com",
        "activated_at": "2024-01-20 14:45:00"
      }
    ]
  }
}

3. Create License #

Create a new license (admin only).

Endpoint: POST /wp-json/easycommerce/v1/licenses

Permissions: Admin

Parameters:

• license_key (string, optional): Custom license key. If omitted, one will be auto-generated
• order_id (integer, required): Associated order ID
• customer_id (integer, required): Associated customer ID
• product_id (integer, required): Associated product ID
• price_id (integer, optional): Associated price ID (default: 1)
• status (string, optional): License status (active, inactive, expired, blocked) (default: active)
• expiry (string, optional): Expiration datetime in Y-m-d H:i:s format (default: empty)
• activation_limit (integer, optional): Maximum number of activations (default: 1)

Sample Request:

curl -X POST "https://your-site.com/wp-json/easycommerce/v1/licenses" \
  -H "X-WP-Nonce: your_nonce_here" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": 456,
    "customer_id": 789,
    "product_id": 101,
    "price_id": 1,
    "status": "active",
    "expiry": "2024-12-31 23:59:59",
    "activation_limit": 5
  }'

Sample Response:

{
  "success": true,
  "data": {
    "message": "License created",
    "id": 124
  }
}

4. Delete License #

Delete a license (admin only).

Endpoint: DELETE /wp-json/easycommerce/v1/licenses/{key}

Permissions: Admin

Parameters:

• key (string, required): License ID or license key to delete

Sample Request:

curl -X DELETE "https://your-site.com/wp-json/easycommerce/v1/licenses/ABC123-DEF456-GHI789" \
  -H "X-WP-Nonce: your_nonce_here" \
  -H "Content-Type: application/json"

Sample Response:

{
  "success": true,
  "data": {
    "message": "License deleted"
  }
}

5. Activate License #

Activate a license for a specific site/domain.

Endpoint: POST /wp-json/easycommerce/v1/licenses/{key}/activate

Permissions: Public

Parameters:

• key (string, required): License key
• product (string, required): Product slug
• email (string, required): Email address associated with the license
• site_url (string, required): URL of the site to activate
• is_test (boolean, optional): Whether this is a test activation (default: false)

Sample Request:

curl -X POST "https://your-site.com/wp-json/easycommerce/v1/licenses/ABC123-DEF456-GHI789/activate" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "premium-plugin",
    "email": "[email protected]",
    "site_url": "https://mysite.com",
    "is_test": false
  }'

Sample Response (Success):

{
  "success": true,
  "data": {
    "code": "license_activated",
    "message": "License activated",
    "activation_id": 567,
    "expiry": "2024-12-31 23:59:59"
  }
}

Sample Response (Error – Invalid License):

{
  "success": false,
  "data": {
    "code": "license_not_found",
    "message": "The license key you entered is invalid!"
  }
}

Sample Response (Error – Email Mismatch):

{
  "success": false,
  "data": {
    "code": "license_email_mismatch",
    "message": "The license key and the email don't match!"
  }
}

Sample Response (Error – Limit Reached):

{
  "success": false,
  "data": {
    "code": "license_limit_reached",
    "message": "License activation limit was reached"
  }
}

6. Deactivate License #

Deactivate a license from a specific site/domain.

Endpoint: POST /wp-json/easycommerce/v1/licenses/{key}/deactivate

Permissions: Public

Parameters:

• key (string, required): License key
• site_url (string, required): URL of the site to deactivate

Sample Request:

curl -X POST "https://your-site.com/wp-json/easycommerce/v1/licenses/ABC123-DEF456-GHI789/deactivate" \
  -H "Content-Type: application/json" \
  -d '{
    "site_url": "https://mysite.com"
  }'

Sample Response (Success):

{
  "success": true,
  "data": {
    "code": "license_deactivated",
    "message": "License deactivated"
  }
}

Sample Response (Error):

{
  "success": false,
  "data": {
    "code": "license_deactivation_failed",
    "message": "Failed to deactivate site"
  }
}

7. Update License #

Update license status.

Endpoint: PUT /wp-json/easycommerce/v1/licenses/{key}

Permissions: Public

Parameters:

• key (string, required): License ID or license key
• status (string, required): New status (active, inactive, expired, blocked)

Sample Request:

curl -X PUT "https://your-site.com/wp-json/easycommerce/v1/licenses/ABC123-DEF456-GHI789" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "blocked"
  }'

Sample Response:

{
  "success": true,
  "data": {
    "message": "License updated"
  }
}

PHP Integration Examples #

License Activation Check #

function check_license_activation($license_key, $product_slug, $site_url) {
    $api_url = 'https://your-site.com/wp-json/easycommerce/v1/licenses/' . $license_key . '/activate';
    
    $response = wp_remote_post($api_url, array(
        'body' => json_encode(array(
            'product' => $product_slug,
            'email' => get_option('admin_email'), // or user's email
            'site_url' => $site_url
        )),
        'headers' => array(
            'Content-Type' => 'application/json'
        )
    ));
    
    if (is_wp_error($response)) {
        return false;
    }
    
    $body = json_decode(wp_remote_retrieve_body($response), true);
    
    if ($body['success']) {
        // License activated successfully
        update_option('my_plugin_license_status', 'active');
        update_option('my_plugin_license_expiry', $body['data']['expiry']);
        return true;
    } else {
        // Handle error
        update_option('my_plugin_license_status', 'inactive');
        return false;
    }
}

Daily License Validation #

function validate_license_daily() {
    $license_key = get_option('my_plugin_license_key');
    $site_url = get_site_url();
    $last_check = get_option('my_plugin_last_license_check');
    
    // Check once per day
    if (!$last_check || (time() - $last_check) > 86400) {
        $api_url = 'https://your-site.com/wp-json/easycommerce/v1/licenses/' . $license_key;
        
        $response = wp_remote_get($api_url, array(
            'headers' => array(
                'Content-Type' => 'application/json'
            )
        ));
        
        if (!is_wp_error($response)) {
            $body = json_decode(wp_remote_retrieve_body($response), true);
            
            if ($body['success']) {
                $license_data = $body['data'];
                
                // Check if current site is activated
                $is_activated = false;
                foreach ($license_data['activations'] as $activation) {
                    if ($activation['site'] === $site_url) {
                        $is_activated = true;
                        break;
                    }
                }
                
                if (!$is_activated || $license_data['status'] !== 'active') {
                    // Deactivate plugin functionality
                    update_option('my_plugin_license_status', 'inactive');
                } else {
                    update_option('my_plugin_license_status', 'active');
                }
            }
        }
        
        update_option('my_plugin_last_license_check', time());
    }
}
add_action('init', 'validate_license_daily');

JavaScript Integration #

// License activation
async function activateLicense(licenseKey, productSlug, email, siteUrl) {
    const response = await fetch('https://your-site.com/wp-json/easycommerce/v1/licenses/' + licenseKey + '/activate', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            product: productSlug,
            email: email,
            site_url: siteUrl
        })
    });
    
    const result = await response.json();
    
    if (result.success) {
        console.log('License activated:', result.data);
        localStorage.setItem('license_status', 'active');
        localStorage.setItem('license_expiry', result.data.expiry);
    } else {
        console.error('License activation failed:', result.data.message);
        localStorage.setItem('license_status', 'inactive');
    }
}

// Check license status
async function checkLicenseStatus(licenseKey) {
    const response = await fetch('https://your-site.com/wp-json/easycommerce/v1/licenses/' + licenseKey);
    const result = await response.json();
    
    if (result.success) {
        const license = result.data;
        console.log('License status:', license.status);
        console.log('Activations:', license.activations);
        return license;
    }
    
    return null;
}

Error Codes #

• license_not_found: License key does not exist
• license_email_mismatch: Email doesn’t match the license purchaser
• license_limit_reached: Maximum activations exceeded
• license_expired: License has expired
• license_mismatch: License doesn’t belong to the specified product
• license_activation_failed: Failed to activate (database error)
• license_deactivation_failed: Failed to deactivate (database error)

Rate Limiting #

The API includes standard WordPress rate limiting. For public endpoints (activation/deactivation), implement additional client-side rate limiting to prevent abuse.

Security Considerations #

1. Always validate license keys server-side
2. Use HTTPS for all API calls
3. Implement proper error handling
4. Store sensitive data securely
5. Regularly validate licenses (recommended: daily)
6. Handle network failures gracefully

Support #

For additional support or questions about the EasyCommerce License Manager API, please contact the EasyCommerce support team.