API Versioning

Understand how Hixbe handles API versioning and backward compatibility

API Versioning Strategy

Hixbe uses a date-based versioning system to ensure predictable API behavior and smooth transitions between versions.

Version Format

Versions follow the format YYYY-MM-DD and are specified in the Hixbe-Version header:

curl -X GET "https://api.hixbe.com/payment/payment_intents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Hixbe-Version: 2026-01-01"

Current Version

Latest Version: 2026-01-01

This is the recommended version for all new integrations. It includes the latest features, improvements, and security enhancements.

Version Lifecycle

Version States

State	Description	Support Level
Active	Fully supported with new features	Full support
Deprecated	Still functional but not recommended	Limited support
Sunset	No longer supported	No support

Deprecation Timeline

When a new version is released:

1. Active Period: 12 months of full support
2. Deprecation Notice: 3 months advance warning
3. Deprecated Period: 6 months of limited support
4. Sunset: Version retired

Backward Compatibility

What We Guarantee

• Existing API endpoints remain functional
• Request/response formats are stable
• Breaking changes are introduced in new versions only
• Deprecation notices provided 3+ months in advance
• Migration guides provided for major changes

What May Change

• New optional fields added to responses
• New endpoints added
• New optional parameters added to requests
• Performance improvements
• Bug fixes that don’t change behavior

Version Headers

Required Headers

# Always include the version header
-H "Hixbe-Version: 2026-01-01"

Version Detection

If no version header is provided, the API will:

1. Return a 400 Bad Request error
2. Include a message specifying the required header

{
  "success": false,
  "error": {
    "code": "MISSING_VERSION_HEADER",
    "message": "The Hixbe-Version header is required",
    "details": {
      "required_header": "Hixbe-Version",
      "current_version": "2026-01-01"
    }
  }
}

Version-Specific Features

Version 2026-01-01 Features

Payment Gateway Enhancements

• Enhanced webhook security with signature verification
• Improved error messages with detailed field validation
• New idempotency key support for all endpoints
• Expanded payment method support

SMS Gateway Improvements

• Bulk SMS with individual delivery tracking
• Enhanced sender ID validation
• Template management system
• Improved balance reporting

Certification & Badge Updates

• Enhanced credential verification
• New audit logging capabilities
• Improved badge management
• Program-based credential organization

Migration Guide

Upgrading to 2026-01-01

1. Review changelog

   Check the changelog for all changes in the new version.

2. Test in sandbox

   Update your integration to use the new version in sandbox first:

   # Test with new version
   curl -X GET "https://sandbox.api.hixbe.com/payment/payment_intents" \
     -H "Authorization: Bearer YOUR_SANDBOX_KEY" \
     -H "Hixbe-Version: 2026-01-01"
   
3. Update production

   Once testing is complete, update your production code:

   // Update your API client
   const client = new HixbeClient({
     apiKey: process.env.HIXBE_API_KEY,
     version: '2026-01-01'  // Update this line
   });
   
4. Monitor for issues

   Watch your application logs and dashboard for any issues after deployment.

Version History

Version	Release Date	Status	Notes
2026-01-01	Dec 2025	Active	Latest features and improvements
2025-06-01	Jun 2025	Deprecated	Use 2026-01-01
2025-01-01	Jan 2025	Sunset	No longer supported

Best Practices

Version Management

• Always specify the version header explicitly
• Use the latest version for new integrations
• Test version upgrades in sandbox first
• Monitor deprecation notices in your dashboard
• Keep your integration documentation updated

Code Organization

JavaScript (Recommended)

// Centralized version management
const HIXBE_CONFIG = {
  version: '2026-01-01',
  baseUrl: process.env.NODE_ENV === 'production'
    ? 'https://api.hixbe.com'
    : 'https://sandbox.api.hixbe.com'
};

class HixbeClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.version = HIXBE_CONFIG.version;
    this.baseUrl = HIXBE_CONFIG.baseUrl;
  }

  async request(endpoint, options = {}) {
    const headers = {
      'Authorization': `Bearer ${this.apiKey}`,
      'Hixbe-Version': this.version,
      'Content-Type': 'application/json',
      ...options.headers
    };

    return fetch(`${this.baseUrl}${endpoint}`, {
      ...options,
      headers
    });
  }
}

Support and Migration Help

Authentication

Learn about API keys and headers

Best Practices

Version management best practices

Changelog

See all version changes and updates

Support

Get help with version upgrades