One API, all versions

The HLC API v3.0 and v4.x versions have been unified into a single, forward-compatible platform. Both legacy and modern authentication methods are supported, enabling v3.0 integrations to access v4.x features without migration.

Version Unification Overview

Backward Compatibility

• Existing v3.0 integrations remain fully functional without modification
• v4.0 and v4.1 features are accessible to all v3.0 API consumers
• Dual authentication support: Both ApiKey header (v3.0) and JWT tokens (v4.x) are accepted
• Flexible URL formats: Both legacy and modern endpoint structures are supported
  • Region-prefixed URLs: https://api.hlc.bike/us/v3.0
  • Version-only URLs: https://api.hlc.bike/v4.0

Migration Strategy

This unified approach enables incremental feature adoption. Organizations can leverage v4.x capabilities while maintaining existing v3.0 integrations, eliminating the need for full-scale rewrites.

New Features for v3.0 Users

The version unification provides v3.0 integrations with access to enhanced v4.x functionality:

• Season-based order management: Create and manage seasonal purchase orders
• Cart price calculation: Preview total order cost before submission, including taxes and shipping

Implementation Example

Using Legacy v3.0 Endpoints

Existing v3.0 code continues to function without modification:

const apiUrl = 'https://api.hlc.bike/us/v3.0'
const apiKey = process.env.HLC_API_KEY

const response = await fetch(`${apiUrl}/Catalog/Brands`, {
  headers: {
    ApiKey: apiKey,
    language: 'en',
  },
})

if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${response.statusText}`)
}

const brands = await response.json()

Accessing v4.x Features from v3.0

You can now call v4.x endpoints using your existing v3.0 authentication:

const apiUrl = 'https://api.hlc.bike/us/v4.1'
const apiKey = process.env.HLC_API_KEY

// Access v4.1 cart preview feature with v3.0 credentials
const response = await fetch(`${apiUrl}/Orders/Prices`, {
  method: 'POST',
  headers: {
    ApiKey: apiKey, // v3.0 authentication works on v4.x endpoints
    'Content-Type': 'application/json',
    language: 'en',
  },
  body: JSON.stringify({
    items: [
      { sku: 'BRK-001', quantity: 2 },
      { sku: 'CHN-045', quantity: 1 },
    ],
  }),
})

const cartPrices = await response.json()
console.log(`Total: $${cartPrices.total}`)