Skip to main content
GET
/
api
/
v1
/
products
/
{product_id}
/
price-history
Price History
curl --request GET \
  --url https://api.example.com/api/v1/products/{product_id}/price-history
{
  "id": "<string>",
  "product_id": "<string>",
  "old_price": 123,
  "new_price": 123,
  "reason": "<string>",
  "created_at": "<string>"
}

Authorization

Required roles: admin, gestor, consultor

Path Parameters

product_id
string
required
UUID of the product to retrieve price history for

Response

Returns an array of price history entries, ordered by creation date.
id
string
Unique identifier for the price history entry (UUID)
product_id
string
UUID of the product this history entry belongs to
old_price
number
Previous price before the change
new_price
number
Updated price after the change
reason
string
Explanation for the price change
created_at
string
Timestamp when the price change occurred (ISO 8601 format)

Example Request

curl -X GET https://api.example.com/api/v1/products/a1b2c3d4-e5f6-7890-abcd-ef1234567890/price-history \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response

[
  {
    "id": "hist-001",
    "product_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "old_price": 4.99,
    "new_price": 5.49,
    "reason": "Seasonal price increase",
    "created_at": "2026-03-01T10:30:00Z"
  },
  {
    "id": "hist-002",
    "product_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "old_price": 4.49,
    "new_price": 4.99,
    "reason": "Supplier cost adjustment",
    "created_at": "2026-02-15T14:20:00Z"
  },
  {
    "id": "hist-003",
    "product_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "old_price": 3.99,
    "new_price": 4.49,
    "reason": "Initial price correction",
    "created_at": "2026-01-10T09:00:00Z"
  }
]

Empty History Response

If a product has no price changes, an empty array is returned:
[]

Use Cases

Price Trend Analysis

Track how product prices have changed over time to identify trends:
  • Seasonal fluctuations
  • Long-term price increases/decreases
  • Frequency of price adjustments

Audit Trail

Maintain compliance and transparency by:
  • Recording who changed prices and when
  • Documenting reasons for price changes
  • Supporting financial audits

Customer Communication

Provide customers with price history to:
  • Explain current pricing
  • Show price stability or volatility
  • Build trust through transparency

Integration Example

Displaying Price History in a Dashboard

async function fetchPriceHistory(productId) {
  const response = await fetch(
    `https://api.example.com/api/v1/products/${productId}/price-history`,
    {
      headers: {
        'Authorization': `Bearer ${token}`
      }
    }
  );
  
  const history = await response.json();
  
  // Display in a chart or table
  history.forEach(entry => {
    console.log(`${entry.created_at}: ${entry.old_price}${entry.new_price}`);
    console.log(`Reason: ${entry.reason}`);
  });
}

Calculating Price Statistics

import requests
from datetime import datetime

def get_price_stats(product_id, token):
    url = f"https://api.example.com/api/v1/products/{product_id}/price-history"
    headers = {"Authorization": f"Bearer {token}"}
    
    response = requests.get(url, headers=headers)
    history = response.json()
    
    if not history:
        return {"message": "No price history available"}
    
    prices = [entry["new_price"] for entry in history]
    
    return {
        "current_price": prices[0],
        "lowest_price": min(prices),
        "highest_price": max(prices),
        "average_price": sum(prices) / len(prices),
        "total_changes": len(history)
    }

Error Responses

401 Unauthorized

Returned when authentication token is invalid or missing.

403 Forbidden

Returned when the authenticated user lacks required role (admin, gestor, or consultor).

404 Not Found

While the endpoint doesn’t explicitly return 404, if a product doesn’t exist, it will return an empty array [].

Build docs developers (and LLMs) love