REST API v1

API Documentation

Integrate PricePager's powerful price tracking capabilities directly into your applications.

Base URL

https://api.pricepager.com/v1

Authentication

All API requests require authentication using an API key. Include your API key in the request header:

Header 
Authorization: Bearer YOUR_API_KEY

Keep your API key secure

Never expose your API key in client-side code or public repositories. Use environment variables to store keys securely.

Getting Your API Key

  1. Log in to your PricePager dashboard
  2. Navigate to API Keys in the sidebar
  3. Click Generate New Key
  4. Copy and securely store your key (it won't be shown again)

Rate Limits

API rate limits vary by plan. Exceeding limits returns a 429 Too Many Requests response.

Plan Requests/minute Requests/day
Free 10 100
Pro 60 5,000
Business 300 50,000

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1640995200

Pagination

List endpoints return paginated results. Use query parameters to navigate through pages of data.

Query Parameters

Parameter Type Default Description
page integer 1 Page number to retrieve
per_page integer 20 Number of items per page (max: 100)

Response Format

Paginated responses include a meta object with pagination details:

{
  "data": [ ... ],
  "meta": {
    "current_page": 2,
    "per_page": 20,
    "total": 87,
    "total_pages": 5,
    "has_more": true
  },
  "links": {
    "first": "https://api.pricepager.com/v1/products?page=1",
    "prev": "https://api.pricepager.com/v1/products?page=1",
    "next": "https://api.pricepager.com/v1/products?page=3",
    "last": "https://api.pricepager.com/v1/products?page=5"
  }
}

Tip: Efficient Pagination

Use the links object to navigate between pages. Check meta.has_more to determine if more results exist.

Error Handling

The API uses standard HTTP status codes and returns JSON error responses with detailed information to help you debug issues.

Error Response Format

Error Response Structure 
{
  "error": {
    "code": "error_code_here",
    "message": "Human-readable error description.",
    "status": 400,
    "details": {}  // Optional: additional context
  }
}

HTTP Status Codes

Status Description
200 Success - Request completed successfully
201 Created - Resource created successfully
204 No Content - Resource deleted successfully
400 Bad Request - Invalid parameters or malformed request
401 Unauthorized - Invalid or missing API key
403 Forbidden - Insufficient permissions for this action
404 Not Found - Resource doesn't exist
422 Unprocessable Entity - Validation errors
429 Too Many Requests - Rate limit exceeded
500 Server Error - Something went wrong on our end

Common Error Examples

Invalid API Key (401)

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or has been revoked.",
    "status": 401
  }
}

Validation Error (422)

{
  "error": {
    "code": "validation_error",
    "message": "The given data was invalid.",
    "status": 422,
    "details": {
      "url": ["The url field is required."],
      "target_price": ["The target price must be a positive number."]
    }
  }
}

Resource Not Found (404)

{
  "error": {
    "code": "resource_not_found",
    "message": "The requested product could not be found.",
    "status": 404
  }
}

Rate Limit Exceeded (429)

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please wait before making another request.",
    "status": 429,
    "details": {
      "retry_after": 60,
      "limit": 60,
      "remaining": 0,
      "reset_at": "2025-01-19T12:01:00Z"
    }
  }
}

Plan Limit Reached (403)

{
  "error": {
    "code": "plan_limit_reached",
    "message": "You have reached your plan's product limit.",
    "status": 403,
    "details": {
      "current_count": 100,
      "plan_limit": 100,
      "upgrade_url": "https://pricepager.com/pricing"
    }
  }
}

Best Practice: Error Handling

Always check the error.code field for programmatic error handling, as error messages may change. Use the details object when available for additional context.

Products

Create, retrieve, and manage tracked products.

GET /products

List all tracked products for your account.

Query Parameters

page integer Page number (default: 1)
per_page integer Items per page (default: 20, max: 100)
status string Filter by status: active, paused

Response

{
  "data": [
    {
      "id": "prod_abc123",
      "url": "https://amazon.com/dp/B09V3KXJPB",
      "name": "Sony WH-1000XM5 Headphones",
      "current_price": 328.00,
      "currency": "USD",
      "lowest_price": 298.00,
      "highest_price": 399.99,
      "status": "active",
      "last_checked": "2025-01-19T10:30:00Z",
      "created_at": "2024-12-01T08:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 45
  }
}
POST /products

Add a new product to track.

Request Body

{
  "url": "https://amazon.com/dp/B09V3KXJPB",
  "target_price": 299.99,
  "notify_on_any_drop": true
}

Response

{
  "data": {
    "id": "prod_xyz789",
    "url": "https://amazon.com/dp/B09V3KXJPB",
    "name": "Sony WH-1000XM5 Headphones",
    "current_price": 328.00,
    "target_price": 299.99,
    "currency": "USD",
    "status": "active",
    "created_at": "2025-01-19T12:00:00Z"
  }
}
GET /products/{"{id}"}

Retrieve details for a specific product including current price, price statistics, and tracking settings.

Response

{
  "data": {
    "id": "prod_abc123",
    "url": "https://amazon.com/dp/B09V3KXJPB",
    "name": "Sony WH-1000XM5 Headphones",
    "current_price": 328.00,
    "target_price": 299.99,
    "currency": "USD",
    "lowest_price": 298.00,
    "highest_price": 399.99,
    "average_price": 335.50,
    "status": "active",
    "check_interval": "6h",
    "notify_on_any_drop": true,
    "store": {
      "name": "Amazon",
      "domain": "amazon.com"
    },
    "last_checked": "2025-01-19T10:30:00Z",
    "next_check": "2025-01-19T16:30:00Z",
    "created_at": "2024-12-01T08:00:00Z",
    "updated_at": "2025-01-19T10:30:00Z"
  }
}
DELETE /products/{"{id}"}

Stop tracking a product and delete all associated data including price history and alerts.

Response

Returns 204 No Content on success.

Warning: This action is irreversible. All price history data for this product will be permanently deleted.

Prices

Access historical price data for tracked products.

GET /products/{"{id}"}/prices

Get price history for a product.

Query Parameters

from date Start date (ISO 8601)
to date End date (ISO 8601)
interval string Data interval: hourly, daily, weekly

Response

{
  "data": {
    "product_id": "prod_abc123",
    "currency": "USD",
    "prices": [
      { "date": "2025-01-19", "price": 328.00 },
      { "date": "2025-01-18", "price": 328.00 },
      { "date": "2025-01-17", "price": 349.99 },
      { "date": "2025-01-16", "price": 349.99 },
      { "date": "2025-01-15", "price": 298.00 }
    ],
    "statistics": {
      "current": 328.00,
      "lowest": 298.00,
      "highest": 399.99,
      "average": 335.50
    }
  }
}

Alerts

Configure price alerts for your tracked products.

GET /alerts

List all configured price alerts for your account.

Query Parameters

product_id string Filter alerts by product ID
active boolean Filter by active status (true/false)
type string Filter by type: price_below, price_drop, back_in_stock

Response

{
  "data": [
    {
      "id": "alert_abc123",
      "product_id": "prod_abc123",
      "product_name": "Sony WH-1000XM5 Headphones",
      "type": "price_below",
      "target_price": 299.99,
      "notify_via": ["email", "webhook"],
      "active": true,
      "triggered_count": 2,
      "last_triggered": "2025-01-15T08:30:00Z",
      "created_at": "2024-12-01T08:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 12
  }
}
POST /alerts

Create a new price alert for a tracked product.

Request Body

product_id string * ID of the product to create alert for
type string * price_below, price_drop, back_in_stock
target_price number Required for price_below type
notify_via array Notification channels: email, webhook (default: ["email"])
Example Request 
{
  "product_id": "prod_abc123",
  "type": "price_below",
  "target_price": 299.99,
  "notify_via": ["email", "webhook"]
}

Response

{
  "data": {
    "id": "alert_xyz789",
    "product_id": "prod_abc123",
    "product_name": "Sony WH-1000XM5 Headphones",
    "type": "price_below",
    "target_price": 299.99,
    "notify_via": ["email", "webhook"],
    "active": true,
    "triggered_count": 0,
    "last_triggered": null,
    "created_at": "2025-01-19T12:00:00Z"
  }
}
DELETE /alerts/{"{id}"}

Delete a price alert. The alert will stop monitoring and no further notifications will be sent.

Response

Returns 204 No Content on success.

Webhooks

Receive real-time notifications when prices change or alerts are triggered.

POST /webhooks

Register a webhook endpoint.

Request Body

{
  "url": "https://your-app.com/webhooks/pricepager",
  "events": ["price.dropped", "alert.triggered"],
  "secret": "your_webhook_secret"
}

Webhook Events

Event Description
price.changed Product price has changed
price.dropped Product price decreased
alert.triggered Price alert condition met
product.unavailable Product went out of stock

Webhook Payload

{
  "event": "price.dropped",
  "timestamp": "2025-01-19T12:30:00Z",
  "data": {
    "product_id": "prod_abc123",
    "product_name": "Sony WH-1000XM5 Headphones",
    "previous_price": 349.99,
    "current_price": 298.00,
    "currency": "USD",
    "url": "https://amazon.com/dp/B09V3KXJPB"
  }
}

Official SDKs

Get started quickly with our official client libraries:

JavaScript
npm install pricepager
Python
pip install pricepager
PHP
composer require pricepager/sdk