woonoow-docs/docs/developer/software-updates/index.mdx

---
title: Software Updates API
description: Distribute software updates with license-based access control
---

The Software Distribution module enables selling WordPress plugins, themes, or any software with automatic update checking, secure downloads, and version management.

## Prerequisites

- Enable **Licensing** module (required)
- Enable **Software Distribution** module in Settings → Modules
- Configure downloadable products with software distribution enabled

## Product Configuration

When editing a downloadable product in WooCommerce, you'll see a new "Software Distribution" section:

| Field | Description |
|-------|-------------|
| **Enable Software Updates** | Allow customers to check for updates via API |
| **Software Slug** | Unique identifier (e.g., `my-plugin`) used in API calls |
| **Current Version** | Latest version number (e.g., `1.2.3`) |

### WordPress Integration (Optional)

Enable "WordPress Plugin/Theme" to add these fields:

- **Requires WP** - Minimum WordPress version
- **Tested WP** - Tested up to WordPress version
- **Requires PHP** - Minimum PHP version

## API Endpoints

### Check for Updates

```
GET /wp-json/woonoow/v1/software/check
POST /wp-json/woonoow/v1/software/check
```

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `license_key` | string | Yes | Valid license key |
| `slug` | string | Yes | Software slug |
| `version` | string | Yes | Current installed version |
| `site_url` | string | No | Site URL for tracking |

**Response:**

```json
{
  "success": true,
  "update_available": true,
  "product": {
    "name": "My Plugin",
    "slug": "my-plugin"
  },
  "current_version": "1.0.0",
  "latest_version": "1.2.0",
  "changelog": "## What's New\n- Added feature X\n- Fixed bug Y",
  "release_date": "2026-02-01 12:00:00",
  "download_url": "https://your-store.com/wp-json/woonoow/v1/software/download?token=..."
}
```

For WordPress plugins/themes, an additional `wordpress` object is included:

```json
{
  "wordpress": {
    "requires": "6.0",
    "tested": "6.7",
    "requires_php": "7.4",
    "icons": { "1x": "...", "2x": "..." },
    "banners": { "low": "...", "high": "..." }
  }
}
```

### Download File

```
GET /wp-json/woonoow/v1/software/download?token=<token>
```

Download tokens are single-use and expire after 5 minutes.

### Get Changelog

```
GET /wp-json/woonoow/v1/software/changelog?slug=<slug>
GET /wp-json/woonoow/v1/software/changelog?slug=<slug>&version=<version>
```

Returns version history with changelogs.

## WordPress Client Integration

Include the updater class in your plugin or theme to enable automatic updates:

### 1. Copy the Updater Class

Copy `class-woonoow-updater.php` from the WooNooW plugin's `templates/updater/` directory to your plugin.

### 2. Initialize in Your Plugin

```php
<?php
// In your main plugin file

require_once plugin_dir_path(__FILE__) . 'includes/class-woonoow-updater.php';

new WooNooW_Updater([
    'api_url'     => 'https://your-store.com/',
    'slug'        => 'my-plugin',
    'version'     => MY_PLUGIN_VERSION,
    'license_key' => get_option('my_plugin_license_key'),
    'plugin_file' => __FILE__,
]);
```

### 3. For Themes

```php
<?php
// In your theme's functions.php

require_once get_theme_file_path('includes/class-woonoow-updater.php');

new WooNooW_Updater([
    'api_url'     => 'https://your-store.com/',
    'slug'        => 'my-theme',
    'version'     => wp_get_theme()->get('Version'),
    'license_key' => get_option('my_theme_license_key'),
    'theme_slug'  => 'my-theme',
]);
```

## Non-WordPress Integration

For other software types, make HTTP requests directly to the API:

### JavaScript Example

```javascript
async function checkForUpdates(licenseKey, currentVersion) {
  const response = await fetch('https://your-store.com/wp-json/woonoow/v1/software/check', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      license_key: licenseKey,
      slug: 'my-software',
      version: currentVersion,
    }),
  });
  
  const data = await response.json();
  
  if (data.update_available) {
    console.log(`Update available: v${data.latest_version}`);
    // Download from data.download_url
  }
  
  return data;
}
```

### Python Example

```python
import requests

def check_for_updates(license_key: str, current_version: str) -> dict:
    response = requests.post(
        'https://your-store.com/wp-json/woonoow/v1/software/check',
        json={
            'license_key': license_key,
            'slug': 'my-software',
            'version': current_version,
        }
    )
    
    data = response.json()
    
    if data.get('update_available'):
        print(f"Update available: v{data['latest_version']}")
        # Download from data['download_url']
    
    return data
```

## Managing Versions

Use the Admin SPA at **Products → Software Versions** to:

- View all software-enabled products
- Release new versions with changelogs
- Track download counts per version
- Set current (latest) version

## Error Codes

| Error | Description |
|-------|-------------|
| `invalid_license` | License key is invalid or expired |
| `product_not_found` | Software slug doesn't match any product |
| `software_disabled` | Software distribution not enabled for product |
| `invalid_token` | Download token expired or already used |
| `module_disabled` | Software Distribution module is disabled |

## Security

- All API endpoints require valid license key
- Download tokens are single-use and expire in 5 minutes
- Rate limiting: 10 requests/minute per license (configurable)
- IP address logged with download tokens