API Reference Guide

Overview

• 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

Full integration

• 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()

• The external application must store the productId and urlId returned by Price2Spy to ensure correct object mapping.
• It is strongly recommended to pass your internal product identifier as the internalId attribute during insertProduct() calls.
• The getCurrentPricingData() operation should be executed as a scheduled background process (typically 1–6 times per day).

• Automated repricing
• Margin calculations
• Competitive analysis
• Reporting and analytics

Partial integration

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

• 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.

• 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.

Partial integration

• 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.

• 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

Step 1: 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

• Swagger Documentation Console: https://api.price2spy.com/rest/swagger-ui.html#/
• Price2Spy Web Interface (GUI): https://spy.price2spy.com/price2spy

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.

Step 2: Obtain Client Credentials

To access the API, you will need:

• CliendID
• 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

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.

Step 3: 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

Step 4: 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

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:

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:

String-To-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

Use that encoded value as the Signature in the Authorization header

Signature Generation Examples

Example: POST Request

String-To-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)

String-To-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:

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

• 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

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.

• 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

• All prices and currencies are exactly as captured on monitored websites. Display settings in the GUI do not affect API responses.
• All dates and times in requests and responses are in UTC. Convert to local timezone as needed in your application.
• When using get-current-pricing-data, note that each product may contain multiple URLs and each URL includes the latest (lastMeasurement) and previous (secondToLastMeasurement) price snapshots.

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 mistake

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:

• Email: support@price2spy.com