API Reference Guide revision
Price2Spy NewsletterSubscribe

Search
API Reference Guide revision
Price2Spy Website
Contact Support
Price2Spy Log in

Overview

What this API does?

This REST API enables secure integration with third-party software and external applications allowing full programmatic access to your account data without logging into the user interface.

Using the API, you can manage your product portfolio end-to-end, including:

  • Creating, updating, activating, and deactivating products
  • Adding, removing, modifying, and managing product URLs for price monitoring
  • Retrieving product data and pricing information across all or selected monitored websites
  • Automating data synchronization with external systems

The API is designed to support backend integrations, data pipelines, reporting systems, and custom automation workflows.

Typical use cases

Depending on your system architecture and data ownership model, integration can be fully automated or partially delegated to the Price2Spy interface.

Full Integration

External application manages products and URLs; Price2Spy provides pricing data.

In this model the external application is the primary system of record for products and their associated URLs.

How it works?

  • The external application creates and maintains product and URL data.
  • Products and URLs are programmatically submitted to Price2Spy using:
    • insertProduct()
    • insertUrl()
  • Price2Spy begins monitoring submitted URLs for pricing changes.
  • The external application periodically retrieves up-to-date pricing data using:
    • getCurrentPricingData()

Partial Integration

⇒ Product and URLs managed in Price2Spy; pricing data consumed by external application.

In this scenario, products and URLs are created and maintained directly within the Price2Spy web interface.

How it works?

  • Users manually manage products and URLs in Price2Spy.
  • The external application periodically retrieves pricing updates via:
    • get-current-pricing-data

Key Characteristics

  • No need to programmatically insert product URLs.
  • The external application can reconstruct product and URL objects using the data returned by getCurrentPricingData(), since the response includes complete object structures.

Typical Use Case

This approach is suitable when:

  • Product management is handled operationally through the Price2Spy interface.
  • The external system only needs access to pricing data for reporting, dashboards, or analytics.
  • In this model, Price2Spy acts both as the product management interface and the monitoring engine.

⇐ External application supplies products and URLs; pricing alerts handled by Price2Spy.

In this model, the external application supplies product URLs but does not retrieve structured pricing data.

How it works?

  • The external system detects or matches competitor products.
  • Newly identified URLs are submitted to Price2Spy using:
    • insert_Url
  • Price2Spy monitors pricing changes.
  • Instead of pulling pricing data via API, the client relies on Price2Spy’s built-in email alert mechanism.

Typical Use Case

This approach is suitable when:

  • The external system already performs product matching or crawling.
  • There is no need to store pricing data internally.
  • Users prefer notification-based workflows instead of data synchronization.
  • In this model, Price2Spy acts primarily as a monitoring and alerting service.

Quick Start

Choose Your Environment

Production Environment

Use this environment for live integrations and regular price monitoring.

REST API Base URL

https://api.price2spy.com/rest/v1

In the production environment, price checks are executed according to your account configuration.

Test Setup (Development)

Price2Spy does not provide a separate public development API endpoint. Instead, testing can be performed directly in your active account – make sure not to delete any relevant data.

Obtain Client Credentials

To access the API, you will need:

  • ClientID
  • Client Secret

These credentials are used to generate the HMAC signature required for authentication.

To obtain credentials:

  • Log in to the Price2Spy interface
  • In the left-side menu, navigate to Integrations >>> API
  • Generate or retrieve your Client ID and Client Secret

These credentials are used to generate the HMAC signature required for authentication.

If you do not have access, contact support@price2spy.com

Keep your Client Secret secure. It should never be exposed in frontend applications or shared publicly.

Time & Data Format Requirements

Timestamps

  • All request and response timestamps use UTC (Coordinated Universal Time)
  • Ensure your integration handles timezone conversion appropriately

Prices & Currencies

  • Prices and currencies are returned exactly as captured on the monitored website
  • Account display settings such as “Show all prices in my currency” do not affect API responses

Explore the API via Swagger

The interactive Swagger interface allows you to:

  • View all available endpoints
  • Inspect request and response models

Swagger URL: https://api.price2spy.com/rest/swagger-ui.html#/

This is the recommended starting point for developers implementing the integration.

What’s Next?

Once your environment is ready and credentials are generated:
  1. Implement HMAC request signing
  2. Send your first authenticated request (e.g. POST /rest/v1/get-products)
  3. Validate the response structure
  4. Schedule background synchronization if needed

Postman Collections and Examples

To simplify API testing with Postman, we have prepared a step by step guide and a ready to use Postman collection. You can access the setup instructions and download the collection using the provided links:

Authentication

Price2Spy API uses HMAC-SHA256 authentication to ensure secure, tamper-proof API access for all requests. This method verifies both the origin and integrity of each request using a shared secret between the client and Price2Spy.

All HMAC authenticated requests must be sent over HTTPS (TLS) for security.

Overview

To authenticate requests, you must include three required elements:
  • Client ID — unique identifier for your integration
  • Client Secret — private key used to generate the HMAC signature
  • HMAC Signature — hash value generated over the request data and secret
Both Client ID and Client Secret are obtained from your Price2Spy account as explained in the previous section.

Required Request Headers

Every authenticated API request must include the following headers:

Header Description
Host API hostname and port (e.g., api.price2spy.com:443)
X-P2S-Date Request timestamp in UNIX Epoch format (within ±15 min of server time)
Authorization HMAC authentication header containing Client ID and signature
Content-Type Must be application/json for POST and PUT requests
Example:
  • Host: api.price2spy.com:443
  • X-P2S-Date: 1700417770
  • Authorization: HmacSHA256 {Client_ID}:{Signature}
  • Content-Type: application/json
Timestamp must be in UNIX Epoch format and must not differ from actual UTC time by more than 15 minutes to prevent replay attacks.

Authorization Header Format

The Authorization header must follow this syntax:
  • Authorization: HmacSHA256 {Client_ID}:{Signature}
Where:
  • HmacSHA256 — indicates the HMAC algorithm used
  • Client_ID — your assigned client identifier
  • Signature — Base64-encoded HMAC-SHA256 signature computed over the request data using your Client Secret

How to Generate the Signature

To build the signature, first construct the String-To-Sign using the canonical request parts:

Signature example
Sign
	HTTP_METHOD + '\n' +
	host_with_port + '\n' +
	content_type + '\n' +
	resource_path + '\n' +
	date_in_unix_epoch + '\n' +
	request_payload
Explanation of each element:
  • HTTP_METHOD — Uppercase HTTP method (e.g., GET, POST)
  • host_with_port — Hostname with port (e.g., api.price2spy.com:443)
  • content_type — Should be application/json for POST/PUT; for GET/DELETE without body, use an empty string
  • resource_path — The path and query string of the API endpoint (e.g., /rest/v1/get-products)
  • date_in_unix_epoch — Value from the X-P2S-Date header
  • request_payload — The full JSON request body; if none, use an empty string
Once you have constructed the string:
  1. Compute the HMAC-SHA256 hash using your Client Secret
  2. Base64-encode the resulting hash value
  3. Use that encoded value as the Signature in the Authorization header

Signature Generation Examples

Example: POST Request
Sign constructed as:
	POST
	api.price2spy.com:443
	application/json
	/rest/v1/get-products
	1700485915
	{"active": true}
  • Compute HMAC-SHA256 over the above string using Client Secret
  • Base64 encode the result
  • Insert into the Authorization header
Example: GET Request (No Body)
Sign constructed as:
	GET
	api.price2spy.com:443
	/rest/v1/get-brands
	1700485915
  • Notice the empty lines for content_type and request_payload
  • Proceed with HMAC and Base64 encoding as above

Common HMAC Errors

When generating or validating HMAC signatures, the API may return standard JSON errors similar to:

Error Message Meaning
HMAC signature mismatch Signature sent does not match expected value
Authorization header with HmacSHA256 scheme not provided Missing or incorrect Authorization header
HMAC invalid timestamp header Timestamp is not valid (wrong format)
HMAC missing timestamp header Missing X-P2S-Date header

Best Practices

  • Ensure all requests include accurate and synchronized timestamps
  • Always compute HMAC using exact request body string, with no added formatting
  • Keep Client Secret secure and never embed it in client-side code

Endpoint Overview

The Price2Spy REST API provides a comprehensive set of endpoints to manage products, URLs, brands, categories, suppliers, and pricing data. Below is a high-level overview of available endpoints grouped by functionality.

Available Endpoints

HTTP Method Endpoint Description
POST /v1/insert-product Add a new product to Price2Spy
POST /v1/insert-url Add a new URL for monitoring for an existing product
POST /v1/update-product Update an existing product’s information
POST /v1/update-url Update an existing URL’s information
POST /v1/delete-product/{id} Delete a product from Price2Spy
POST /v1/delete-url/{id} Delete a URL from a product
POST /v1/get-current-pricing-data Retrieve current pricing data for products and URLs
POST /v1/get-products Retrieve detailed information about products
POST /v1/get-urls Retrieve detailed information about URLs
GET /v1/get-brands Retrieve the list of brands
GET /v1/get-categories Retrieve the list of categories
GET /v1/get-suppliers Retrieve the list of suppliers

Notes

  • All endpoints are accessible via the base URL: https://api.price2spy.com/rest/v1
  • All requests must include HMAC authentication headers as defined in the Authentication section
  • Response format is JSON
  • Endpoints support individual operations

Endpoint Details

This section provides a detailed example of a Price2Spy API endpoint to demonstrate request structure, response format, and usage conventions.

For full parameter definitions, all available endpoints, and possible error codes, please refer to the Swagger API documentation:
https://api.price2spy.com/rest/swagger-ui.html#/rest-api

Example Endpoint

POST /v1/get-current-pricing-data

Purpose:

Retrieve current pricing data for products and their monitored URLs. This endpoint is commonly used for analytics, reporting, and automated price monitoring.

Request Example
curl -X POST "https://api.price2spy.com/rest/v1/get-current-pricing-data" \
	-H "Content-Type: application/json" \
	-H "X-P2S-Date: 1700417770" \
	-H "Authorization: HmacSHA256 {Client_ID}:{Signature}" \
	-d '{
		"active": true,
		"brandName": "Example Brand",
		"searchMode": "LIKE"
	}'
Response Example (truncated)
{
	"products": {
		"product": [
			{
				"productId": 123,
				"productName": "Example Product",
				"brandName": "Example Brand",
				"minPrice": {
					"amount": 9.99,
					"currency": "EUR"
				},
				"maxPrice": {
					"amount": 12.49,
					"currency": "EUR"
				},
				"urls": {
					"url": [
						{
							"siteHumanName": "Example Shop",
							"lastMeasurement": {
								"price": {
									"amount": 10.99,
									"currency": "EUR"
								},
								"available": true,
								"dateChecked": "2026-01-23 09:55:00"
							}
						}
					]
				}
			}
		]
	}
}

Notes

  • This example demonstrates request structure, HMAC authentication, and JSON response format.
  • Use the Swagger link above to explore:
    • All endpoint parameters (required vs optional)
    • Full request and response object models
    • Possible error responses (401 Unauthorized, 403 Forbidden, 404 Not Found, etc.)
By providing a single illustrative example and referencing Swagger for detailed specifications, your documentation remains concise, readable, and maintainable for both developers and non-technical users.

Error Handling

This section provides key recommendations and guidelines to ensure reliable, secure, and efficient integration with the Price2Spy REST API.

Authentication

  • Always generate HMAC signatures using your Client Secret. Never expose the secret in frontend code.
  • Ensure that your X-P2S-Date header uses the current UTC timestamp in UNIX Epoch format. Requests with timestamps outside ±15 minutes of server time will be rejected.
  • Validate your HMAC computation by testing first in a TEST account before running production requests.

Common HMAC errors include:

  • Hmac signature mismatch — verify Client Secret and payload string
  • Invalid timestamp — check X-P2S-Date
  • Authorization header missing — ensure Authorization header format is HmacSHA256 {Client_ID}:{Signature}
  • Always implement retry logic for transient network issues or 5xx server responses.
  • Log all errors for troubleshooting and audit purposes.

Request and Response Handling

  • Always use HTTPS for secure communication.
  • Ensure correct JSON formatting. HMAC signatures are sensitive to even minor changes in whitespace or line endings in the request payload.
  • For endpoints returning large datasets (e.g., getCurrentPricingData), consider scheduling background jobs rather than running synchronously in real-time. Typical schedules: 1–6 times per day.
  • Store returned productId and urlId for proper object mapping in your external application.

Data and Timestamp Considerations

  • Notice the empty lines for content_type and request_payload
  • Proceed with HMAC and Base64 encoding as above

Rate Limits

The Price2Spy REST API enforces a rate limit to ensure fair usage and stable performance:
  • Limit: 4 requests per second per client (based on Client ID)
  • Requests exceeding this limit may result in HTTP 429 Too Many Requests responses
  • Clients should implement throttling or queuing to stay within the limit
  • Retry after delay is recommended when receiving 429 responses

Tips for compliance:

  • Schedule frequent background jobs with pacing to avoid bursts

Monitor 429 responses and implement exponential backoff before retrying

Frequently Asked Questions (FAQ)

Why do I get “Hmac signature mismatch” error?

This is the most common issue when integrating with the API and usually indicates that the generated signature does not match the server-side calculation.

Common causes

  • Request body differs between:
    • the string-to-sign
    • and the actual HTTP request
  • Missing or incorrect headers:
    • Content-Type
    • Host
  • Incorrect formatting of the string-to-sign (missing line breaks, wrong order, etc.)
  • Using a different timestamp in headers vs signature calculation

How to fix it

  • Ensure the payload is identical in both:
    • string-to-sign
    • actual request body
  • Always include required headers:
    • Host
    • X-P2S-Date
    • Authorization
  • For POST and PUT requests:
    • include Content-Type: application/json
  • Carefully follow the exact structure of the string-to-sign (including line breaks)

Do I need to include Content-Type header in my request?

Yes, for POST and PUT requests

  • Content-Type: application/json is mandatory
  • If included in the string-to-sign, it must also be present in the request

For GET requests

  • Content-Type is not required
  • It should typically be:
    • empty in the string-to-sign
    • omitted from the request headers

Do headers used in the signature need to be sent in the request?

Yes — always

Any header used in the string-to-sign must also be included in the actual request.

Minimum required headers

  • Host
  • X-P2S-Date
  • Authorization

Additional rules

  • If Content-Type is included in the string-to-sign → it must also be sent
  • Missing headers will result in authentication failure

Why am I getting 401 Unauthorized even though my signature looks correct?

A 401 Unauthorized response with message:

Hmac signature mismatch

usually indicates a mismatch between your request and the expected format.

Things to check

  • Is the Host header included in the request (not just in the string-to-sign)?
  • Are all headers identical between:
    • signature calculation
    • actual HTTP request
  • Is the timestamp valid and not expired?
  • Are you using:
    • correct Client ID
    • correct Client Secret

Should I use future timestamps when generating the signature?

No — use the current timestamp.

Best practice

  • Generate timestamp using current server time (time() or equivalent)
  • Avoid future timestamps unless explicitly required
  • Ensure your system clock is synchronized (e.g. via NTP)

How should the request body be handled when generating the signature?

Important rules

  • The request body must be:
    • JSON-encoded
    • identical in:
      • string-to-sign
      • actual HTTP request

Common mistakes

  • Different spacing or formatting
  • Encoding inconsistencies
  • Using different payloads in signing vs sending

How do I construct the string-to-sign correctly?

The string-to-sign must follow this exact structure:

HTTP_METHOD

HOST

CONTENT_TYPE

RESOURCE_PATH

TIMESTAMP

REQUEST_BODY

Key rules

  • Each element must be separated by a newline character (\n)
  • Order must be exact
  • Empty values (e.g. for GET requests) must still be included as empty lines

Why are GET requests failing while POST requests work?

This usually happens due to incorrect handling of Content-Type and request body.

For GET requests

  • Content-Type should be empty
  • Request body should be empty
  • Both must still be included in the string-to-sign as empty values

Common mistakes

Including:

  • non-empty Content-Type
  • or body content

This leads to signature mismatch.

What are the minimum required headers for a valid request?

Every request must include:

  • Host
  • X-P2S-Date
  • Authorization

Additionally

  • Content-Type is required for:
    • POST
    • PUT
    • DELETE (if body is present)

What is the best way to debug signature issues?

Recommended approach

  • Log the following:
    • string-to-sign
    • generated signature (before and after Base64 encoding)
    • request headers
    • request body
  • Compare your implementation with a known working example
  • Verify each component step-by-step:
    • method
    • host
    • content type
    • path
    • timestamp
    • body

What is the most common integration mistake overall?

The most frequent issue is:

Mismatch between the string-to-sign and the actual HTTP request

This includes:

  • different payload
  • missing headers
  • incorrect formatting

Support

If you encounter any issues or have questions related to the Price2Spy API, please contact our support team: