Lifecycle and Deprecation Policy
WEX Health & Benefits Platform APIs follow a structured lifecycle to ensure stability, predictability, and clear communication with our partners. Understanding this lifecycle helps you plan integrations and manage changes effectively.
API Lifecycle Stages
All WEX APIs progress through four distinct stages:
Preview → Public → Deprecated → Retired 1. Preview
**Status:** Experimental and subject to change
Characteristics:
- New APIs or features in active development
- Available for testing and early adoption
- May undergo breaking changes without notice
- Limited or no SLA guarantees
- Ideal for proof-of-concept and feedback
Identification:
- Marked with
[PREVIEW]in documentation - May include version suffix (e.g.,
/v1-preview/) - Clearly labeled in API Reference
Best Practices:
- Use in non-production environments only
- Provide feedback to help shape the final API
- Expect potential changes to endpoints, parameters, and responses
- Do not build production systems on Preview APIs
Support:
- Community support and documentation
- Direct feedback channels to product team
- No guaranteed response times
2. Public
**Status:** Generally available and production-ready
Characteristics:
- Stable and fully supported
- Covered by SLA commitments
- Breaking changes follow deprecation policy
- Recommended for production use
- Comprehensive documentation and support
Identification:
- Standard version numbering (for example,
/v1/,/v2/) - No special labels in documentation
- Listed in production API catalog
Best Practices:
- Use for all production integrations
- Monitor release notes for updates
- Implement proper error handling
- Follow security best practices
Support:
- Full technical support
- SLA-backed availability
- Regular updates and bug fixes
- Security patches and improvements
3. Deprecated
**Status:** Scheduled for retirement
Characteristics:
- Still functional but not recommended for new integrations
- Minimum 12-month notice before retirement
- Security updates and critical bug fixes only
- Migration path to replacement API provided
- No new features added
Identification:
- Marked with
[DEPRECATED]in documentation - Deprecation notice in API responses (via headers)
- Retirement date clearly communicated
**Deprecation Notice:** When an API is deprecated, you’ll receive:
- Email notification to registered contacts
- In-app notifications in Dev Portal
Timeline:
- **T+0 (Announcement):** Deprecation announced with retirement date
- **T+6 months:** Migration guide and replacement API available
- **T+9 months:** Reminder notifications sent
- **T+12 months:** API retired (minimum timeline)
Best Practices:
- Plan migration as soon as deprecation is announced
- Test replacement API in non-production environment
- Update integrations before retirement date
- Monitor deprecation headers in API responses
Support:
- Migration assistance available
- Documentation for replacement APIs
- Extended support for critical issues
- Consultation for complex migrations
4. Retired
**Status:** No longer available
Characteristics:
- API endpoints return
410 Gonestatus - No longer accessible or supported
- All traffic redirected or blocked
- Documentation archived
What Happens:
- All requests return
410 Gone - No data processing occurs
- Monitoring and logging discontinued
- Documentation moved to archive
If You’re Still Using a Retired API:
- Immediate action required
- Contact WEX Support for emergency assistance
- Expedited migration support available
- Temporary extension may be possible (fees may apply)
Versioning Strategy
Version Numbering
WEX APIs use semantic versioning in the URL path:
https://platform.benefits.wexglobal.com/v{major}/resourceExamples:
/v1/consumers- Version 1/v2/consumers- Version 2/v1-preview/new-feature- Preview version
Breaking vs. Non-Breaking Changes
Breaking Changes (require new major version):
- Removing or renaming endpoints
- Removing or renaming request/response fields
- Changing field data types
- Adding required parameters
- Changing authentication methods
- Modifying error response structures
Non-Breaking Changes (can be added to existing version):
- Adding new endpoints
- Adding optional parameters
- Adding new response fields
- Adding new error codes
- Performance improvements
- Bug fixes
Backward Compatibility
- Public APIs maintain backward compatibility within major versions
- New optional fields may be added without version change
- Clients should ignore unknown fields in responses
- Deprecated fields remain functional until version retirement
Emergency Changes
In rare cases, WEX may need to make emergency changes:
Security Vulnerabilities
- Immediate patches may be applied
- Notification within 24 hours
- Backward compatibility maintained when possible
- Extended support for affected partners
Critical Bugs
- Fixes deployed as soon as possible
- May affect API behavior
- Detailed communication provided
- Rollback procedures available
Service Disruptions
- Temporary changes to ensure stability
- Real-time status updates
- Post-incident reports published
- Compensation per SLA terms
Frequently Asked Questions
How long will a Public API be supported?
Public APIs are supported indefinitely until officially deprecated.
Can I continue using a Deprecated API?
Yes, deprecated APIs remain functional until the retirement date. However, we strongly recommend migrating to the replacement API as soon as possible.
What if I need more time to migrate?
Contact your WEX account manager to discuss extension options. Extensions may be available for complex integrations (fees may apply).
How do I know which version to use?
Always use the latest Public (non-deprecated) version for new integrations. Check the API Reference for current recommendations.
Will Preview APIs always become Public?
Not necessarily. Preview APIs may be modified significantly or discontinued based on feedback. Only use Preview APIs for testing.
What happens to my data when an API is retired?
Data is not affected by API retirement. Only the API endpoint is retired. Data remains accessible through replacement APIs.