API Reference Guide
API Reference Guide

Overview

The Price2Spy RESTAPI gives your systems read and write access to your Price2Spy account: products, the competitor URLs tracked for them, sites, measurements and pricing data. This guide is for the developers who build that integration.

Item Value
Base path /api/v1
Base URL https://<api-host>/api/v1 — your Price2Spy contact supplies the host
Format JSON in and out, Content-Type: application/json on every request with a body
Authentication HMAC-SHA256 signature on every request (next section)
Credentials A client ID and a client secret, issued per account by Price2Spy
Interactive reference Swagger UI at /api/v1/swagger-ui/index.html where enabled — it describes the API but cannot call it, because it cannot sign requests

Your credentials identify your account. Every request reads and writes that account’s data only, and no endpoint takes an account ID.

Conventions used throughout

  • Field names are camelCase. Fields with no value are left out of responses rather than sent as null , except on sites and price buckets.
  • Every list endpoint is paginated and returns the same envelope (see Common rules).
  • Every update is a PATCH : fields you leave out keep their current value.
  • Every failure returns the same error body, whatever the status (see Errors and status codes).

Authentication

Every request carries two headers: an HMAC-SHA256 signature of the request, keyed with your client secret, and the time you signed it.
Authorization: HmacSHA256 <clientId>:<base64-signature> X-P2S-Date: <unix time in seconds>

Building the signature

  1. Take the current Unix time in whole seconds, e.g. 1791878400 . Send it as X-P2S-Date .
  2. Build the string to sign: the fields below, joined by a single newline ( \n , byte 0x0A).
  3. Compute HMAC-SHA256 over that string, using your client secret (UTF-8 bytes) as the key.
  4. Base64-encode the result (standard alphabet, with padding) and send it in Authorization .
METHOD\nHOST\n[CONTENT-TYPE\n]RESOURCE\nDATE\nBODY
Field Value Notes
METHOD GET , POST , PATCH , DELETE Uppercase
HOST api.example.com:443 The host you call, with or without its port. Both forms are accepted
CONTENT-TYPE The Content-Type header exactly as sent, e.g. application/json Only on POST, PATCH and DELETE, and only when you send a Content-Type header: sign it exactly as sent (if you send application/json; charset=UTF-8 , sign that whole string). With no header, as is usual on a DELETE or POST /automatch/{id}/promote , leave out the value and its newline, as on a GET
RESOURCE /api/v1/products? page=1&size=20 Path including /api/v1 , then ? and the query string if there is one. Percent-encoded exactly as it goes on the wire
DATE 1791878400 The same string you send in X-P2S-Date
BODY The raw request body The exact bytes sent. Empty on a GET , so the string ends with the newline after DATE
Example — the string signed for GET /api/v1/products?page=1&size=20 :
GET
api.example.com:443
/api/v1/products?page=1&size=20
1791878400

Rules that cause most signature failures

  • Sign exactly what you send. The server checks the request line as it arrives, still percent-encoded. If your HTTP library re-encodes the URL after you signed it (an apostrophe becoming %27 , for example), the signature will not match. Build the final encoded URL first, sign that string, and send that string.
  • Never put a literal space in a query. Encode it as %20 and sign the %20 .
  • Sign the body bytes you send. If your client re-serialises the JSON after signing (reordering keys, changing whitespace), the signature breaks. Serialise once, sign those bytes, send those bytes.
  • Keep your clock right. X-P2S-Date must be within 900 seconds (15 minutes) of the server’s clock, either direction. Sign each request fresh; do not reuse a signature.
  • Keep the secret on your server. Never ship it in browser or mobile code.

Signing examples

Each example signs and sends one request. Each signs the bare host name, sends Content-Type: application/json on every write, and sends the exact body bytes it signed. Pass resource already percent-encoded, e.g. /api/v1/products?sku=O%27Brien .

Test values

Check your implementation against these before calling the API. Secret my-client-secret , date 1791878400 , host api.example.com :
Request Body Expected signature
GET
/api/v1/products?page=1&size=20
none B/o+cDZ1wt7CE/u/Ub3WJu/UeWn7YRQOgmv9klR1FUI =
POST
/api/v1/product
{“productName”:”Blue kettle”,”sku”:”KET001″} b5KtT1gYjSqlkwZlildOEzS4Tmocqci/Kb8ny8x2w5M =

Java (11+)

import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;
import java.nio.charset.StandardCharsets;
import java.time.Instant;
import java.util.Base64;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
public class Price2SpyClient {
private static final String HOST = "api.example.com";
private static final String CLIENT_ID = "your-client-id";
private static final String CLIENT_SECRET = "your-client-secret";
private final HttpClient http = HttpClient.newHttpClient();
public HttpResponse send(String method, String resource, String
json) throws Exception {
String date = String.valueOf(Instant.now().getEpochSecond());
byte[] body = json == null ? new byte[0] :
json.getBytes(StandardCharsets.UTF_8);
boolean write = !method.equals("GET");
StringBuilder toSign = new StringBuilder()
.append(method).append('\n')
.append(HOST).append('\n');
if (write) toSign.append("application/json").append('\n');
toSign.append(resource).append('\n').append(date).append('\n');
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new
SecretKeySpec(CLIENT_SECRET.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
mac.update(toSign.toString().getBytes(StandardCharsets.UTF_8));
mac.update(body);
String signature = Base64.getEncoder().encodeToString(mac.doFinal());
HttpRequest.Builder request =
HttpRequest.newBuilder(URI.create("https://" + HOST + resource))
.header("Authorization", "HmacSHA256 " + CLIENT_ID + ":" +
signature)
.header("X-P2S-Date", date)
.method(method, body.length == 0 ? BodyPublishers.noBody() :
BodyPublishers.ofByteArray(body));
if (write) request.header("Content-Type", "application/json");
return http.send(request.build(),
HttpResponse.BodyHandlers.ofString());
}
}

C# (.NET6+)

Use ByteArrayContent , not StringContent : StringContent appends ; charset=utf8 to the content type, which then no longer matches what you signed.
using System.Net.Http.Headers;
using System.Security.Cryptography;
using System.Text;
public class Price2SpyClient
{
private const string Host = "api.example.com";
private const string ClientId = "your-client-id";
private const string ClientSecret = "your-client-secret";
private readonly HttpClient _http = new();
public async Task SendAsync(HttpMethod method,
string resource, string? json = null)
{
var date = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();
var body = json is null ? Array.Empty() :
Encoding.UTF8.GetBytes(json);
var write = method != HttpMethod.Get;
var toSign = new StringBuilder()
.Append(method.Method).Append('\n')
.Append(Host).Append('\n');
if (write) toSign.Append("application/json").Append('\n');
toSign.Append(resource).Append('\n').Append(date).Append('\n');
var head = Encoding.UTF8.GetBytes(toSign.ToString());
var message = new byte[head.Length + body.Length];
head.CopyTo(message, 0);
body.CopyTo(message, head.Length);
using var hmac = new
HMACSHA256(Encoding.UTF8.GetBytes(ClientSecret));
var signature = Convert.ToBase64String(hmac.ComputeHash(message));
var request = new HttpRequestMessage(method, $"https://{Host}
{resource}");
request.Headers.TryAddWithoutValidation("Authorization", $"HmacSHA256
{ClientId}:{signature}");
request.Headers.Add("X-P2S-Date", date);
if (write)
{
request.Content = new ByteArrayContent(body);
request.Content.Headers.ContentType = new
MediaTypeHeaderValue("application/json");
}
return await _http.SendAsync(request);
}
}

Python (3.8+, requests)

import base64, hashlib, hmac, json, time
import requests
HOST = "api.example.com"
CLIENT_ID = "your-client-id"
CLIENT_SECRET = "your-client-secret"
def send(method, resource, body=None):
date = str(int(time.time()))
payload = b"" if body is None else json.dumps(body, separators=(",",
":")).encode("utf-8")
write = method != "GET"
fields = [method, HOST] + (["application/json"] if write else []) +
[resource, date]
to_sign = ("\n".join(fields) + "\n").encode("utf-8") + payload
digest = hmac.new(CLIENT_SECRET.encode("utf-8"), to_sign,
hashlib.sha256).digest()
signature = base64.b64encode(digest).decode("ascii")
headers = {"Authorization": f"HmacSHA256 {CLIENT_ID}:{signature}", "XP2S-Date": date}
if write:
headers["Content-Type"] = "application/json"
return requests.request(method, f"https://{HOST}{resource}",
headers=headers, data=payload)

JavaScript(Node.js 18+)

fetch percent-encodes some characters in the URL (an apostrophe, for example), so pass resource already encoded.
import base64, hashlib, hmac, json, time
import requests
HOST = "api.example.com"
CLIENT_ID = "your-client-id"
CLIENT_SECRET = "your-client-secret"
def send(method, resource, body=None):
date = str(int(time.time()))
payload = b"" if body is None else json.dumps(body, separators=(",",
":")).encode("utf-8")
write = method != "GET"
fields = [method, HOST] + (["application/json"] if write else []) +
[resource, date]
to_sign = ("\n".join(fields) + "\n").encode("utf-8") + payload
digest = hmac.new(CLIENT_SECRET.encode("utf-8"), to_sign,
hashlib.sha256).digest()
signature = base64.b64encode(digest).decode("ascii")
headers = {"Authorization": f"HmacSHA256 {CLIENT_ID}:{signature}", "XP2S-Date": date}
if write:
headers["Content-Type"] = "application/json"
return requests.request(method, f"https://{HOST}{resource}",
headers=headers, data=payload)

Common rules

These rules apply to every endpoint. The endpoint reference only lists exceptions to them.

Pagination

Every list endpoint takes page and size in the query string and returns the same envelope.
 
Parameter Default Allowed
page 1 1 or more
size 20
  • 1 to 5 on /current-pricing-data
  • 1 to 500 on every other list endpoint
{
"items": [ ... ],
"page": 1,
"size": 20,
"total": 137,
"totalPages": 7
}
total counts all matching records, not just this page. A page past the end returns 200 with “items”: [] and the real total , not an error. To read everything, request pages 1 to totalPages .

Writes and their responses

 

VerbUsed forSuccessBody returned
POST to a collection, e.g. /products
Create201 CreatedThe created
record
POST to a record action, e.g. /automatch/{id}/promote
An action200 OKDepends on the
action
PATCHUpdate200 OKThe updated
record
DELETEDelete204 No ContentNone
A write returns the record’s own fields. Values the API calculates or joins from other records on a GET — a URL’s site name, the last measurement, last-checked dates — are not in a write response. Read the record with GET if you need them.

Updates (PATCH)

Every update is partial. Send the record’s id and only the fields you want to change
You send Meaning
Field left out Keep the current value
“field”: “new value” Set it
“field”: null
  • Clears on /products : text fields, prices, brand/category/supplier/metadata names, custom fields
  • Clears on /urls : the three notes
  • Clears on /sites : customName
  • 400 on productName , a product’s active , a URL’s url
  • Keeps every other field, and every field on brands, categories, suppliers and account metadata
  • A body with nothing but the id is rejected with 400 . Send at least one field to change.
  • To clear the email recipients of a brand, category, supplier or account metadata, send an empty list: “emailRecipient”: [] .
  • Resending values that are already stored is accepted. On products and URLs nothing is written, so the record’s modified date does not change.

Request bodies

  • Unknown field names are ignored, not rejected. A misspelled field is silently dropped, so compare the response with what you sent.
  • Text is trimmed, and blank text counts as no value. “” or ” “ on a required field is a 400 ; on a PATCH it is treated exactly like null .
  • Types are strict. A number is refused where a boolean is expected ( 1 for true ), a decimal where a whole number is expected ( 12.7 for 12 ), and a number where a named value is expected. Quoted forms are accepted: “12” for a number, “true” for a boolean.
  • Prices accept 0 to 9,999,999,999.99. Negative values are refused. A third decimal place is rounded when stored.

Dates

Responses give dates as ISO-8601 instants in UTC, e.g. 2026-09-21T11:08:09Z . Date filters accept four forms:
You send Meaning
2026-08-01T12:00:00Z That instant, UTC
2026-08-01T14:00:00+02:00 That instant, at the given offset
2026-08-01T14:00:00 That time in server time (Central European Time, as in Paris: UTC+1 in winter, UTC+2 in summer)
2026-08-01 The whole day: from 00:00:00 on a …From filter, to 23:59:59 on a …To filter
  • Ranges include both ends.
  • A space instead of T ( 2026-08-01 12:00:00 ) is rejected.
  • In a query string, + is read as a space. Send an offset as %2B02:00 to be safe. A raw +02:00 also works, but only if it is also exactly what you signed.
Pricing-data dates ( /pricing-data/… ) have two extra limits. A date more than one year in the past is a 400 naming that field. A range wider than one year is a 400 on dateRangeWithinLimit . Defaults for missing dates are listed per endpoint in the reference.

Field names

The names in this guide are the exact names on the wire. Two to note: a product’s purchase price is costPrice , and custom fields are customField1 to customField10 everywhere

Currency

Prices are converted to your account currency when your account has an exchange rate for the site’s currency; otherwise they stay in the site’s currency. The currency field always names the one used. Shipping cost and shelf price are never converted.

Errors and status codes

Every failure returns one JSON shape, whatever the status: statusCode and message, plus fieldErrors when a value failed validation, or errorId on a server error.

Errors and status codes

Every failure returns one JSON shape, whatever the status: statusCode and message , plus fieldErrors when a value failed validation, or errorId on a server error.
{
"statusCode": 400,
"message": "Bad request",
"fieldErrors": [
{ "field": "size", "message": "Page size cannot exceed 500" },
{ "field": "page", "message": "Invalid value, but got: abc" }
]
}
{
"statusCode": 500,
"message": "An unexpected error occurred",
"errorId": ""
}
Status When What to do
400 Bad Request A query or body value failed validation ( fieldErrors names each field); the body is not valid JSON; the Authorization header is present but malformed; X-P2S-Date is missing, not a number, or more than 900 seconds from server time; a business rule refused the request ( message says which) Fix the request. For the date header, check your clock
401 Unauthorized No Authorization header or a scheme other than HmacSHA256 ; unknown client ID; signature does not match; API access is not enabled for the account See Troubleshooting. The message is deliberately brief
403 Forbidden The record cannot be changed, e.g. a product that is not editable Do not retry
404 Not Found The record does not exist in your account, or the path does not exist. A list that matches nothing is a 200 with no items, not a 404 Check the ID and the path
405 Method Not Allowed The path exists but not with this verb. The Allow header lists the verbs it takes Use a listed verb
409 Conflict The change conflicts with existing data, e.g. a name already in use Change the value
415 Unsupported Media Type A body was sent without Content-Type: application/json Send that header
429 Too Many Requests You exceeded your rate limit (below) Wait at least one second, then retry
500 Internal Server Error An unexpected failure on our side Retry later. If it persists, send us the errorId

Rate limit

Each client ID may make a fixed number of requests per second, set for your account by Price2Spy. Spare capacity does not carry over beyond that one-second allowance. When you exceed it, you get 429 with the limit in the message:
{
"statusCode": 429,
"message": "Exceeded the rate limit of 4 requests/second. Reduce the
request rate to resume uninterrupted service."
}
There is no Retry-After header. Wait one second and retry, and pace parallel requests to stay under the limit. Ask your Price2Spy contact if you need a higher limit.

Endpoint reference

The endpoints are in the Endpoints tab: a summary of all 43, then one sub-tab per section, in the same order as Swagger UI.

Troubleshooting

Most integration problems are signing problems, and the error message tells you which kind.

You get LIkely cause Fix
401 “Hmac signature mismatch” The string you signed differs from the request you sent Work through the checklist below
401 “Hmac auth header missing” No Authorization header, or it does not start with exactly HmacSHA256 (case matters) Send HmacSHA256 <clientId>:<signature>
400 “Authorization header with HmacSHA256 scheme not provided” The header does not match HmacSHA256 <clientId>: <signature> , e.g. extra spaces or a missing colon One space after the scheme, none elsewhere
400 “HMAC timestamp expired” X-P2S-Date is more than 900 seconds from server time, often because milliseconds were sent instead of seconds Send whole seconds and keep the clock synced (NTP)
400 “Hmac missing timestamp header” or “Hmac invalid timestamp header” X-P2S-Date is absent or not a whole number Send Unix seconds, e.g. 1791878400
401 “API access denied for client ID …” API access is not enabled for your account Contact Price2Spy
401 “Authentication failed” or “Invalid client ID” The client ID is not recognised Check the client ID you were issued
A date filter returns less than you expected A date without an offset is read as server time (Central European Time), not UTC Add Z or an offset
A field you sent did not change The field name is misspelled, so it was ignored Compare with the reference; the response shows what was stored
429 under load Parallel workers share one client ID’s per-second limit Throttle across all workers together

Signature mismatch checklist

Check these in order. They are listed by how often they cause the problem.

  1. Encoding. Is the resource you signed character-for-character what went on the wire? Log the final URL your HTTP library sends and compare.
  2. Base path. Does the resource include /api/v1 ?
  3. Content type. On POST , PATCH and DELETE , included only when you send a ContentType header, and exactly as sent, including any ; charset=… . Left out on GET and on a write sent without that header.
  4. Body. Did you sign the exact bytes sent? Re-serialising JSON after signing breaks the signature.
  5. Date. Is the same string in the X-P2S-Date header and in the signed string?
  6. Newlines. Single \n between fields, no \r . On a GET the string ends with \n after the date.
  7. Secret. Used as UTF-8 bytes, not base64-decoded or hex-decoded first.

If you are still stuck, send your Price2Spy contact the method, the full URL as sent, and the X-P2S-Date value from a failing request. Never send your client secret.

Endpoint reference

The API has 43 endpoints in 8 sections, one sub-tab each. All paths below start with /api/v1 . Every list also takes page and size , and every endpoint can return the errors under Errors and status codes in Guide ; only endpoint-specific ones are listed in the sections.
 
Section Method and path Purpose Success
Products GET /products Search products 200, paged
  POST /products Create a product 201
PATCH /products Update a product 200
DELETE /products/{id} Delete a product and its URLs 204
URLs GET /urls Search competitor URLs 200, paged
POST /urls Add a URL to a product 201
PATCH /urls Update a URL 200
DELETE /urls/{id} Delete a URL 204
Sites GET /sites List sites your URLs are on 200, paged
PATCH /sites Set a site’s custom name, priority or alert setting 200
Measurements GET /measurements Price checks for one URL 200, paged
Pricing data GET /pricing-data/last-price-change URLs whose latest price changed 200, paged
GET /pricing-data/product-pricehistory/{id} All price checks for one product 200, paged
GET /pricing-data/current-pricingdata Products with their URLs and current prices 200, paged (max 50)
Price buckets GET /price-buckets Price ranges and product counts 200, paged
Metadata GET, POST, PATCH and DELETE …/{id} on /brands, /categories, /suppliers, /metadata/{one|two|three} Manage brands, categories, suppliers and your three custom lists 200 / 201 / 200 / 204
Automatch GET /automatch List automatch suggestions 200, paged
POST /automatch/{automatchUrlId}/promote Accept a suggestion as a URL 200
POST /automatch/{urlId}/demote Turn a promoted URL back into a rejected suggestion 200
POST /automatch/{automatchUrlId}/reject Reject a suggestion 200
Named values are uppercase and case-sensitive: DAYS , not days .

Products

GET/products

Searches your products, ordered by product ID. All filters are optional and combine with AND.

 
Parameter Type Matches
productId integer That product
productName, sku, internalId text Per searchMode
url text, 3+ characters Products with a URL matching this text, per searchMode
categoryId, brandId, supplierId, metadata1Id, metadata2Id, metadata3Id integer That linked record
metadataFilter.categoryName, .brandName, .supplierName, .metadata1Name, .metadata2Name, .metadata3Name text The linked record’s name, per searchMode
customFieldFilter.customField1 … customField10 text Per searchMode
comment1, comment2 text Per searchMode
dateChangeFrom, dateChangeTo date Products with at least one URL whose latest price check falls in the range. Combined with url, the same URL must match both
active boolean Active or inactive products
frequencyType/span> + frequencyInterval DAYS/HOURS + integer (max 60) Products checked at exactly that frequency. Send both or neither
searchMode LIKE (default) or EQUAL LIKE matches text anywhere in the value; EQUAL matches the whole value. Applies to every text filter in the request
In LIKE mode, % and _ in your text act as wildcards.

Product fields, in response order:

 
Field Type Notes
productId integer
productName text Unique within your account
checkFrequencyType, checkFrequencyInterval DAYS / HOURS, integer How often the product’s URLs are checked. A whole number of days is always shown as DAYS
active, showInReports, repricingExcluded boolean
sku, internalId text
categoryName, categoryId, brandName, brandId, supplierName, supplierId text, integer
minPrice, maxPrice price object Lowest and highest current price across the product’s active URLs: {“currency”: “EUR”, “amount”: 12.30}. Converted, see Currency in the Guide.
lastChecked, nextCheck, lastChanged date Last time a URL was checked, next scheduled check, time of the most recent stored measurement
urlCount integer
targetPrice, costPrice … ceilingPrice, bottomPrice decimal
metadata1Name, metadata1Id … metadata3Name, metadata3Id text, integer Your three custom lists
customField1 … customField10, comment1, comment2 text
dateAdded, dateModified, addedById, modifiedById date, integer

POST/products

Creates a product. Only productName is required.
{
"productName": "Blue kettle 1.7 l",
"sku": "KET-001",
"checkFrequencyType": "DAYS",
"checkFrequencyInterval": 1,
"brandName": "Acme",
"costPrice": 18.50,
"targetPrice": 29.99
}
 
Field Required Rules
productName yes Up to 250 characters, unique in your account
checkFrequencyType, checkFrequencyInterval no Send both. If either is missing, your plan’s default is used. Allowed values below
active no Default true
repricingExcluded no Default false
sku, internalId no Up to 250 characters
targetPrice, costPrice, ceilingPrice, bottomPrice no 0 to 9,999,999,999.99
categoryName, brandName, supplierName, metadata1Name, metadata2Name, metadata3Name no Up to 250 characters. A name that does not exist yet is created
customField1 … customField10 no Up to 250 characters
comment1, comment2 no

Check frequency allowed by plan

 
Plan Allowed Default
Weekly checking 7, 14, 30 or 60 days 7 days
All other plans 1, 2, 3, 5, 7, 14 or 30 days; also 3, 4, 6, 8 or 12 hours on premium accounts 1 day
HOURS 48 and DAYS 2 are the same frequency. Errors: 409 if the name is already used; 400 if the frequency is not allowed on your plan.

PATCH/products

Updates a product. Send productId and the fields to change, with the same rules as create.

{ “productId”: 1042, “targetPrice”: 27.99, “comment1”: null }
  • null clears a field, with three exceptions: productName and active answer 400 , and checkFrequencyType / checkFrequencyInterval keep the current frequency.
  • A metadata name links the product to that record, creating it if needed; null unlinks it.
  • Frequency changes only when both checkFrequencyType and checkFrequencyInterval are sent.

Errors: 404 product not found; 403 the product is not editable; 409 name already used,
or activating the product would exceed your plan’s limit; 400 frequency not allowed

DELETE/products/{id}

Deletes the product together with its URLs and their price history. This cannot be undone. Errors: 404 not found; 409 the product cannot be deleted

URLs

A URL is one competitor page tracked for a product. Each URL belongs to a site, which the API works out from the address.

GET /urls

Searches your URLs, ordered by product ID, then URL ID. Text filters match anywhere in the value.

 
Parameter Type Matches
id integer That URL
productId integer URLs of that product
productName, sku, internalId text The owning product
query text, 3+ characters Product name, SKU or internal ID. When used, the four filters above it are ignored. Under 3 characters, query itself is ignored
active boolean Active or inactive URLs

URL fields, in response order:

Field Type Notes
urlId, productId integer
url text
productName text The name stored for this URL, which may differ from the product’s name
siteHumanName, siteCountryISOCode text The site’s name and country. Your own name for the site (see Sites) and your account’s country for it take precedence
showInReports, active boolean
deactivatedBy, deactivationDate integer, date Who deactivated the URL and when
multiplicator decimal Multiplier applied to the price found on the page. Default 1
note1 … note3, image1Url … image3Url text
counterFailed, lastError integer, text Consecutive failed checks and the last error
lastChecked date
lastMeasurement, secondToLastMeasurement measurement See Measurements . price is converted, see Currency in the Guide
automatchUrl automatch Present when the URL came from an automatch suggestion. See Automatch
dateAdded, dateModified, addedById, modifiedById date, integer

POST /urls

Adds a URL to a product. If the site is new to Price2Spy, it is created.

{ “productId”: 1042, “url”: “https://shop.example.com/kettle-blue”, “multiplicator”: 2 }
Field Required Rules
productId yes A product in your account
url yes A valid URL, up to 2,000 characters
active no Default true
showInReports no Default true
note1, note2, note3 no
multiplicator no Greater than 0, up to 4 decimal places and 8 digits before the point. Only on sites where multipliers are enabled
Errors: 404 product not found; 409 the product already has a URL on this site, the site does not allow a multiplier, or adding an active URL would exceed your plan’s URL, site or stealth limit.

PATCH/urls

Updates a URL. Send urlId and the fields to change.
Field Rules
url Must stay on the same site. To move to another site, delete the URL and add a new one. Cannot be cleared
active Setting false records the deactivation date. null keeps
showInReports null keeps
note1, note2, note3 null clears
multiplicator As on create. Send 1 to reset; null keeps
counterFailed 0 or more. Send 0 to reset the failure counter
Errors: 404 URL not found; 409 the URL is not editable, the new address is on another site, the multiplier is not allowed, or reactivating would exceed a plan limit

DELETE/urls/{id}

Deletes the URL and its price history. A URL created by promoting an automatch suggestion cannot be deleted; demote it instead (see Automatch ).

Errors: 404 not found; 409 the URL cannot be deleted.

Sites

A site is a web shop. You see only the sites where your account has at least one URL.

GET /sites

Lists your sites: those with a priority first (lowest number first), then by name.

Parameter Type Matches
searchTerm text Custom name or site name, anywhere in the value
id integer That site
customName, siteName, homeUrl text Anywhere in the value
countryCode text Exact ISO country code
priority integer Exact. 0 means no priority
hasAccountSpecific, ignoreEmailAlerts boolean
Site fields. Unlike other resources, empty fields are returned as null.
Parameter Type Notes
id integer
name text The site’s name in Price2Spy
customName text Your own name for the site
homeUrl, countryCode text
priority integer 0 if not set
hasAccountSpecific boolean Your account has its own settings for this site
ignoreEmailAlerts boolean The site is left out of your email alerts
priceRule object or null {“field”, “operation”, “value”} — your price rule for the site

PATCH /sites

Send id and any of these. The response is the full site, as on GET.
Field Rules
customName Up to 100 characters, null clears
priority Integer. null keeps
ignoreEmailAlerts Boolean. null keeps
Error: 404 the site is not one of yours.

Measurements

A measurement is one price check of one URL

GET /measurements

Returns the price checks for one URL, newest first.

ParameterTypeNotes
urlIdintegerrequired
dateCheckedFrom, dateCheckedTodateOptional. No range limit

 

Errors: 404 URL not found.

Measurement fields, in response order:

Field Type Notes
urlId, url, siteHumanName integer, text Only in product price history, where rows come from several URLs
dateChecked date
price price object {“currency”: “EUR”, “amount”:12.30}. Converted, see Currency in the Guide
available boolean Always present
shippingCost, shelfPrice decimal As found on the site, not converted
shippingTime, shippingDetails, stockStatus, seller, promotionText text
isOnPromotion boolean
customField1 … customField10 text
screenshotUrl text Link to the screenshot taken during the check
 

Pricing data

Three read-only views of your prices. On all three, a date more than one year in the past is a 400 naming that field, and a range wider than one year is a 400 on dateRangeWithinLimit .

When you leave dates out

You send last-price-change product-price-history current-pricing-data
No dates Last 30 days Last year All current data, no date filter
Start only Start to now (at most one year) Start to now (at most one year) From the start
End only One year before the end to the end, but no earlier than one year ago Same Up to the end
Both As sent As sent As sent
 

GET /pricing-data/last-price-change

Returns one row per URL whose latest price differs from the price before it, newest change first. A price appearing or disappearing counts as a change; a URL checked only once does not appear. The date range applies to the latest check.

Parameter Type Notes
type INCREASE or DECREASE Optional. Without it, every change is listed, including a price appearing or disappearing; with it, only rows where both prices exist
latestChangeDateFrom, latestChangeDateTo date See the table above
 
Fields, in response order. latestPrice , previousPrice and myOwnPrice are plain decimals, converted (see Currency in the Guide ); each one’s currency is in the matching …Currency field.
Group Fields
The URL dateChanged (time of the latest check), productId, productName, siteName, urlId, url
Latest check latestPrice, latestCurrency, LatestAvailability, latestOnPromotion, latestShippingCost, latestShippingTime, latestShippingDetails, latestStockStatus, latestSeller, latestShelfPrice, latestPromotionText, latestCustomField1 … latestCustomField10
Check before it previousDateChanged, then the same fields with the previous prefix
Your own site myOwnPrice, myOwnCurrency, myOwnAvailability — the latest check of this product on your own shop, when there is one
To tell an increase from a decrease in the response, compare latestPrice with previousPrice.

GET /pricing-data/product-price-history/{id}

Returns every price check across all URLs of product {id} , newest first. Each row is a measurement (see Measurements ) and includes urlId, url and siteHumanName , so you can tell the URLs apart.
 
Parameter Type Notes
dateCheckedFrom, dateCheckedTo date See the table above
 
Errors: 404 product not found.

GET /pricing-data/current-pricing-data

Returns products with all their URLs, and each URL’s current and previous price check, ordered by product name. size is at most 50 here, because each product carries its URLs.
It takes the same filters as GET /products , with three differences: metadata names are plain parameters ( categoryName , brandName , supplierName , metadata1Name … metadata3Name , customField1 … customField10 ), there are no frequency filters, and dateChangeFrom / dateChangeTo match any check in the range, not only a URL’s latest.
  • Only products with at least one URL are listed.
  • The url filter chooses which products are listed; each listed product still returns all its URLs.
  • With dates, only products checked within the range are listed. Each URL’s currentMeasurement is its newest check within the range, previousMeasurement the check before it, which may be earlier than the range, and URLs not checked in the range are left out.
Product fields: productId , productName , sku , internalId , active , showInReports , checkFrequencyType , checkFrequencyInterval , nextCheck , targetPrice , costPrice , the category, brand, supplier and metadata names and IDs, customField1 … customField10 , comment1 , comment2 , urlCount , dateLastMeasurement , dateLastChange , minPrice , maxPrice , dateAdded , dateModified , addedById , modifiedById , and urls .
Each entry in urls : urlId , url , productName (the name stored for the URL), siteHumanName , siteCountryIsoCode , active , measure , showInReports , counterFailed , lastError , lastChecked , note1 … note3 , image1Url … image3Url , dateAdded , dateModified , addedById , modifiedById , automatch , currentMeasurement , previousMeasurement . The two measurements have the measurement fields, without urlId , url and siteHumanName .
Note the spelling siteCountryIsoCode here, against siteCountryISOCode on /urls ( URLs ).

Price buckets

GET /price-buckets

Lists your price ranges, lowest first, with the number of products whose price on your own shop falls in each. Filters match exactly: id , name , priceFrom , priceTo . Both ends of a range are inclusive, so a price on a shared boundary is counted in both ranges
Field Type Notes
id, accountId integer
name text
priceFrom, priceTo decimal priceTo is null for an open-ended range
numberOfProducts integer
 

Metadata

Automatch suggestions are competitor pages Price2Spy found that may match your products. You can promote a suggestion into a tracked URL, or reject it.

List Path Product field
Brands /brands brandName
Categories /categories categoryName
Suppliers /suppliers supplierName
Account metadata 1, 2, 3 /metadata/one, /metadata/two, /metadata/three metadata1Name , metadata2Name , metadata3Name
Naming a value on a product that does not exist yet in its list creates it there. Below, {list} stands for any of these paths.

GET {list}

Lists the entries, active first, then by priority (highest first), then by name. Filters: id (exact), name (anywhere in the value), active .
Fields: id , name , active , priority , emailRecipients (a list of email addresses, omitted when there are none), dateAdded , dateModified (absent until the entry is first updated)

POST {list}

Creates an entry.

{ “name”: “Acme”, “priority”: 5, “emailRecipient”: [“pricing@example.com”] }
Field Required Rules
name yes Up to 250 characters, unique within that list
active no Default true
priority no Integer. Default 0
emailRecipient no Valid addresses, each up to 100 characters; together up to 500 characters including one separator between each pair
The request field is emailRecipient (singular) and the response field is emailRecipients (plural).
Errors: 409 the name is already used in that list.

PATCH {list}

Takes id and any of the same fields. Here null or a missing field both mean keep. To remove all email recipients, send “emailRecipient”: [] .
Errors: 404 not found; 409 the name is already used in that list.

DELETE {list}/{id}

Removes an entry that no product uses. Errors: 404 not found; 409 the entry is still used by products.

Automatch

Automatch suggestions are competitor pages Price2Spy found that may match your products. You can promote a suggestion into a tracked URL, or reject it.

Status Meaning approved in the response
UNPROCESSED Not decided yet absent
APPROVED Promoted to a URL true
REJECTED Rejected, or demoted after promotion false

GET​/automatch

Lists suggestions. The order is not fixed, so do not rely on the position of a row across pages.

Parameter Type Matches
id integer That suggestion
productId integer Suggestions for that product
name, sku, internalId text The product’s value, exactly
status APPROVED , REJECTED , UNPROCESSED
dateAutomatchFrom, dateAutomatchTo date When the suggestion was found
Fields:  id, productId, urlId (the URL created from it, once promoted), url, matchAccuracy, automatchDate, approved, approvedDate, dateAdded, dateModified, addedById, modifiedById

POST​/automatch/​{automatchUrlId}/promote

Creates an active URL from the suggestion and marks it approved. No body. Returns 200 with the new URL’s ID: {“urlId”: 98765} . Errors: 404 not found; 409 already promoted, or the product already has this URL or a URL on this site.

POST​/automatch/​{urlId}/demote

Takes the ID of a URL created by promotion, not a suggestion ID. Deletes that URL and its price history and marks the suggestion rejected. No body; returns 200 with no body. Errors: 404 URL not found; 409 the URL did not come from automatch.

POST​/automatch/​{automatchUrlId}/reject

Rejects an unprocessed suggestion. No body; returns 200 with no body. Errors: 404 not found; 409 already promoted or already processed.