# PERS API Changelog

> Public changelog for the PERS Platform API.
Tracking started April 2026.
**Current Version:** 2.0.17


## v2.0.17 - 2026-06-03

### 🔧 Improvements

- **Enhanced Platform Detection**: Added automatic User-Agent parsing as fallback when SDK doesn't provide platform information (OS, browser, device type)
- **Data Quality Tracking**: Platform data now includes quality indicator (`platformSource: 'sdk' | 'auto'`) to distinguish authoritative vs auto-detected information
- **Mobile Browser Tracking**: Mobile browsers (Chrome, Safari on phones/tablets) now correctly tracked as `channel: 'web'` - check `platform.deviceType` to distinguish mobile vs desktop web users


### 🔒 Security

- Added database-level unique email constraint per tenant to prevent duplicate registrations and race conditions


## v2.0.17 - 2026-05-30

### ✨ New Features

- **Attribution Tracking**: New attribution tracking for analytics across all entities (users, claims, redemptions, bookings)
- **DataSource Headers**: SDK can send `x-source-channel`, `x-source`, `x-source-medium`, `x-source-campaign` headers for campaign tracking


### 🔧 Improvements

- Auto-detects channel/source from User-Agent and Referer headers when SDK headers not provided
- Standalone serverless function for booking operations
- Users now have `registrationSource` field for analytics


## v2.0.15 - 2026-05-09

### ✨ New Features

- **Business Ownership**: Added `ownerBusinessId` field to campaigns, redemptions, and token metadata for tracking which business owns/promotes the entity
- **Owner Business Loading**: Added `?include=ownerBusiness` query parameter to load owner business entity details
- **Owner Business Filtering**: Added `?ownerBusinessId` filter parameter to campaigns, redemptions, and token metadata endpoints


### ⚠️ Breaking Changes

- **Deprecated CampaignBusinessEngagement**: Use `TriggerSource.businessId` for business participation tracking instead
- **Business Loading**: `?include=businesses` now extracts business IDs from TriggerSources instead of deprecated CampaignBusinessEngagement


## v2.0.14 - 2026-05-18

### ✨ New Features

- **Booking Terminology**: Renamed "reservation" to "booking" throughout the API for clarity
- **Simplified Booking Types**: Booking requirement values now: `'active'`, `'future'`, `'past'`, `'active_future'`, `'any'`, or `null` (removed `'none'`)
- **Enhanced Redemption Includes**: Redemptions now support `?include=userInfo,booking` to load user field validation and booking eligibility data
- **Booking Query Filters**: `GET /bookings` endpoint now supports `?userId` and `?businessId` query parameters


### ⚠️ Breaking Changes

- **Terminology Change**: All "reservation" references changed to "booking" (`reservationRequirement` → `bookingRequirement`)
- **Removed Endpoint**: `GET /users/:id/bookings` removed - use `GET /bookings?userId=:id` instead
- **Type Change**: `BookingRequirementType` value `'none'` removed - use `null` instead


## v2.0.13 - 2026-04-29

### ✨ New Features

- **Transaction Metadata URIs**: Added `metadataUri` field to transactions for tracking IPFS/storage URLs of NFT metadata
- **Structured Auth Errors**: Token refresh failures now return specific error codes (`REFRESH_TOKEN_EXPIRED`, `REFRESH_TOKEN_REVOKED`) for programmatic detection
- **Redemption Type Management**: Added `PUT /redemptions/types/:id` and `DELETE /redemptions/types/:id` endpoints for admin management


### 🔧 Improvements

- **DPoP Clock Tolerance**: Increased tolerance for corporate environments with clock drift (10 min past, 5 min future)


## v2.0.12 - 2026-04-26

### ✨ New Features

- **Date Range Filtering**: Added `dateFrom` and `dateTo` query parameters to campaign claims and redemption redeems endpoints
- **Multi-Tag Filtering**: Added `tags` parameter (OR match) on campaigns, redemptions, and businesses for flexible tag-based queries
- **Business Search**: Added `search` parameter to `GET /businesses` endpoint for name-based searching
- **Immediate Activation**: Added `isActive` option to activate redemptions and token metadata immediately upon creation


### 🐛 Bug Fixes

- **User Endpoints**: Fixed `PUT /users/me`, `POST /users/info`, and `PUT /users/:identifier` to return virtual wallets in response
- **Date Validation**: Invalid date formats now return proper `400 Bad Request` errors instead of silently failing


## v2.0.11 - 2026-04-25

### ✨ New Features

- **Custom Field Definitions**: Added support for custom user information fields with validation rules
- **User Info Validation**: New `POST /users/info` endpoint for submitting and validating custom field data
- **Geocoding v2**: Enhanced geocoding with support for address components, place IDs, and improved accuracy
- **Analytics Enhancements**: Added `totalClaims`, `totalRedemptions`, `totalBurns` metrics to user analytics
- **Owner Business Filtering**: Analytics endpoints now support `ownerBusinessId` filter for business-specific reporting


### 🔧 Improvements

- **Auto-Enrichment**: Analytics results now automatically include campaign/redemption names and owner business IDs
- **Transaction Status Filtering**: Analytics now filters to `SUCCEEDED` and `BROADCASTED` transactions by default
- **SQL Query Performance**: Fixed PostgreSQL column quoting and JOIN syntax for analytics queries


## v2.0.10 - 2026-04-01

### ✨ New Features

- **OIDC Discovery**: Added `/.well-known/openid-configuration` endpoint for enterprise SSO integration
- **Webhook Metadata**: Webhook trigger endpoint now returns structured response with `executionId`, `statusCode`, `durationMs`


### 🔧 Improvements

- Improved platform stability for high-traffic multi-tenant scenarios