# Release Notes

Track the latest updates, new features, and changes to the FarPay API. This section provides information about version updates, deprecations, and improvements.

## Current Version: v2

The current stable version of the FarPay API is **v2**. All documentation in this guide refers to v2 endpoints and features.

## API Versioning

FarPay uses URL-based versioning where the version number is included in the API base URL:

```
https://api.farpay.io/v2
```

## Recent Updates

### Version 2.1.0 (Latest)

**Release Date:** January 2024

#### New Features

* **Enhanced Payment Filtering**: Added support for filtering payments by payment reference
* **Improved Error Messages**: More detailed error responses for better debugging
* **Rate Limiting Headers**: Added rate limit information in response headers

#### Improvements

* **Performance Optimization**: Faster response times for large data sets
* **Better Date Handling**: Improved date format validation and processing
* **Enhanced Logging**: More comprehensive API request logging

#### Bug Fixes

* Fixed issue with invoice status updates not reflecting immediately
* Resolved problem with agreement cancellation in certain scenarios
* Corrected payment amount calculations for partial refunds

### Version 2.0.0

**Release Date:** December 2023

#### Major Changes

* **New Base URL**: Changed from v1 to v2 endpoints
* **Enhanced Security**: Improved authentication and authorization
* **Better Error Handling**: Standardized error response format

#### New Endpoints

* Enhanced customer management endpoints
* Improved order creation and management
* Better invoice and payment tracking

#### Deprecations

* **v1 API**: The v1 API is now deprecated and will be discontinued
* **Legacy Endpoints**: Some old endpoints have been removed or replaced

## Migration Guide

### From v1 to v2

If you're migrating from v1 to v2, here are the key changes:

#### Base URL Change

```javascript
// Old (v1)
const baseUrl = 'https://api.farpay.io/v1';

// New (v2)
const baseUrl = 'https://api.farpay.io/v2';
```

#### Authentication

```javascript
// v1 - API key in query parameter
const url = 'https://api.farpay.io/v1/customers?apiKey=your-key';

// v2 - API key in header
const headers = {
  'X-API-KEY': 'your-api-key',
  'Accept': 'application/json'
};
```

#### Response Format

```javascript
// v1 - Different response structure
{
  "success": true,
  "data": [...]
}

// v2 - Direct data response
[...]
```

## Deprecated Features

### v1 API (Deprecated)

The v1 API is deprecated and will be discontinued. Please migrate to v2 as soon as possible.

**Discontinuation Date:** December 31, 2024

### Legacy Endpoints

The following endpoints have been deprecated in v2:

* `/subscriptions` - Use `/agreements` instead
* `/paymentsets` - Functionality merged into `/payments`

## Breaking Changes

### Version 2.0.0 Breaking Changes

1. **Authentication Method**: API key must be sent in header, not query parameter
2. **Response Format**: Direct data response instead of wrapped format
3. **Error Codes**: New standardized error response format
4. **Date Formats**: Stricter date format validation

### Migration Checklist

* [ ] Update base URL to v2
* [ ] Move API key to request headers
* [ ] Update response parsing logic
* [ ] Handle new error response format
* [ ] Validate date formats
* [ ] Test all endpoints
* [ ] Update documentation

## Support Timeline

| Version | Status       | Support Until     |
| ------- | ------------ | ----------------- |
| v2      | Current      | Ongoing           |
| v1      | Deprecated   | December 31, 2024 |
| v0      | Discontinued | N/A               |

## Production Environment

For live applications, use the production environment:

```
https://api.farpay.io/v2
```

## Support and Feedback

### Getting Help

* **Documentation**: This guide and [interactive documentation](https://api.farpay.io/docs)
* **Support**: Contact us through [our website](https://farpay.io)

### Providing Feedback

We welcome feedback on the API and documentation:

* **Feature Requests**: Submit through support channels
* **Bug Reports**: Include detailed error information
* **Documentation**: Help us improve this guide

## Related Resources

* [API Documentation](README.md) - Complete API reference
* [Authentication](authentication.md) - Setup and authentication
* [Examples](examples.md) - Integration examples