> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.repliers.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# List Price Change Tracking - Developer Implementation Guide

## Overview

The List Price Change tracking feature automatically maintains a chronological log of all price changes for listings. This provides valuable insights for buyers and enables powerful filtering capabilities for finding properties with recent price adjustments.

**Important Note**: This feature became available in August 2025. Only price changes that occurred after the feature launch will be logged in the `listPriceLog` array. Historical price changes from before August 2025 are not included in this data.

## Data Structure

When a listing's price changes, a `listPriceLog` array is automatically created and maintained:

```
{
  "listingId": "12345",
  "currentListPrice": "689000.00",
  "listPriceLog": [
    {
      "updatedOn": "2025-08-15T16:08:04.668Z",
      "type": "decrease",
      "currentListPrice": "689000.00",
      "previousListPrice": "689900.00"
    },
    {
      "updatedOn": "2025-08-15T19:02:44.025Z",
      "type": "increase",
      "currentListPrice": "689900.00",
      "previousListPrice": "689000.00"
    },
    {
      "updatedOn": "2025-08-15T19:51:49.623Z",
      "type": "decrease",
      "currentListPrice": "689000.00",
      "previousListPrice": "689900.00"
    }
  ]
}
```

### Field Descriptions

* **updatedOn**: ISO 8601 timestamp when the price change occurred
* **type**: Either `"increase"` or `"decrease"`
* **currentListPrice**: The new price after the change (as string with decimal)
* **previousListPrice**: The price before the change (as string with decimal)

## API Filtering Parameters

### Basic Price Change Type Filtering

**Parameter**: `lastPriceChangeType` **Values**: `increase` | `decrease`

Filter listings based on their most recent price change direction.

### Time-Based Filtering

**Parameters**:

* `minPriceChangeDateTime`: Filter for price changes after this date/time
* `maxPriceChangeDateTime`: Filter for price changes before this date/time

**Supported Formats**:

* Date only: `2025-08-11`
* Full datetime: `2025-08-11 10:55:28`

## API Request Examples

### Basic Examples

#### 1. Find All Active Listings With Price Reductions

```
GET https://api.repliers.io/listings?lastPriceChangeType=decrease
```

*Returns all listings where the most recent price change was a decrease*

#### 2. Find All Active Listings With Price Increases

```
GET https://api.repliers.io/listings?lastPriceChangeType=increase
```

*Returns all listings where the most recent price change was an increase*

### Time-Based Examples

#### 3. Price Reductions in Last 24 Hours

```
GET https://api.repliers.io/listings?lastPriceChangeType=decrease&minPriceChangeDateTime=2025-08-17
```

*Assumes today's date is 2025-08-18*

#### 4. Price Changes Within Specific Timeframe

```
GET https://api.repliers.io/listings?minPriceChangeDateTime=2025-08-10&maxPriceChangeDateTime=2025-08-15
```

#### 5. Recent Price Drops with Precise Timing

```
GET https://api.repliers.io/listings?lastPriceChangeType=decrease&minPriceChangeDateTime=2025-08-11 10:55:28
```

## Implementation Best Practices

### 1. Data Processing

* Always check if `listPriceLog` exists before displaying
* Sort log entries by `updatedOn` if order is important for your use case
* Convert string prices to numbers for calculations: `parseFloat(price)`

### 2. API Usage

* Use time-based filters to limit dataset size and improve response times
* Combine parameters to create targeted queries
* Consider pagination for large result sets

### 3. User Experience

* Display price changes with clear visual indicators (red for decreases, green for increases)
* Show both dollar amounts and percentages for price changes
* Provide context like "Price reduced 3 days ago"

### 4. Error Handling

* Check API response status codes for filtering errors
* Verify date format compatibility
* Ensure proper URL encoding for datetime parameters

## Common Pitfalls to Avoid

1. **Assuming listPriceLog always exists**: New listings or listings without price changes won't have this array
2. **Historical data limitations**: Price changes before August 2025 are not tracked - this feature only logs changes from August 2025 forward
3. **Not handling string prices**: Prices are returned as strings - convert to numbers for calculations
4. **Ignoring timezone**: All timestamps are in UTC - convert to local timezone for display
5. **Overlooking parameter combinations**: Combine filters effectively for targeted results

## Testing Your Implementation

### Test Cases to Consider

1. **No price changes**: Listing without `listPriceLog` array
2. **Single price change**: Listing with one entry in `listPriceLog`
3. **Multiple price changes**: Listing with several price adjustments
4. **Recent vs. old changes**: Test time-based filtering accuracy

## Support and Troubleshooting

For technical support or questions about implementation:

* Check API response status codes for filtering errors
* Verify date format compatibility
* Ensure proper URL encoding for datetime parameters
* Contact API support team with specific error messages and request examples