Skip to content

GetPrice API reference

API reference#

Look up competitor prices for your own SKUs and feed them into your ERP, BI or pricing tools. You get the same prices you see in the GetPrice dashboard.

Authentication#

Send your API key in the Authorization header: Authorization: Bearer gp_live_…. Never put the key in a URL. An admin creates your organisation's one key in Settings → API & Integrations; it is shown once, and the same page regenerates it. Scopes are listed in GET /v1/me.

ScopeGrants
catalog:readyour products, competitors, SKU links
matches:readcomparison sets (competitor matches and prices)
skus:writecreate, replace and remove SKU links
BASE=https://api.getprice.ai/v1
curl "$BASE/me" \
  -H "Authorization: Bearer $GETPRICE_API_KEY"
import os

import requests

BASE = "https://api.getprice.ai/v1"
KEY = os.environ["GETPRICE_API_KEY"]

resp = requests.get(
    f"{BASE}/me",
    headers={"Authorization": f"Bearer {KEY}"},
    timeout=30,
)
resp.raise_for_status()
me = resp.json()
name = me["company"]["name"]
per_minute = me["limits"]["per_minute"]
print(f"Connected: {name}, {per_minute}/min")
interface Me {
  company: { name: string };
  limits: { per_minute: number };
}

const BASE = "https://api.getprice.ai/v1";
const KEY = process.env.GETPRICE_API_KEY;
const url = `${BASE}/me`;
const res = await fetch(url, {
  headers: { Authorization: `Bearer ${KEY}` },
});
if (!res.ok) {
  throw new Error(`GetPrice returned ${res.status}`);
}
const me = (await res.json()) as Me;
const { name } = me.company;
const perMinute = me.limits.per_minute;
console.log(`Connected: ${name}, ${perMinute}/min`);
<?php
$base = "https://api.getprice.ai/v1";
$key = getenv("GETPRICE_API_KEY");
$ch = curl_init("$base/me");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $key",
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($body === false || $status >= 400) {
    throw new RuntimeException(
        "GetPrice returned $status: $body"
    );
}
$data = json_decode(
    $body, true, flags: JSON_THROW_ON_ERROR
);

printf(
    "Connected: %s, %d/min\n",
    $data["company"]["name"],
    $data["limits"]["per_minute"],
);
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;
using Naming = System.Text.Json.JsonNamingPolicy;

var key = Environment.GetEnvironmentVariable(
    "GETPRICE_API_KEY");
var api = new Uri("https://api.getprice.ai/v1/");
var http = new HttpClient { BaseAddress = api };
http.Timeout = TimeSpan.FromSeconds(30);
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", key);
var json = new JsonSerializerOptions
{
    PropertyNamingPolicy = Naming.SnakeCaseLower,
};

var res = await http.GetAsync("me");
res.EnsureSuccessStatusCode();
var me = await res.Content
    .ReadFromJsonAsync<Me>(json);
var name = me!.Company.Name;
var perMinute = me.Limits.PerMinute;
Console.WriteLine(
    $"Connected: {name}, {perMinute}/min");

record Me(Company Company, Limits Limits);
record Company(string Name);
record Limits(int PerMinute);

Errors#

Errors use RFC 9457 problem details with Content-Type: application/problem+json. Branch on code, never on title or detail, and quote request_id when you contact support.

Error response401
{
  "type": "https://api.getprice.ai/errors/unauthenticated",
  "title": "Authentication required",
  "status": 401,
  "detail": "Send Authorization: Bearer <API key>.",
  "code": "unauthenticated",
  "request_id": "req_7f3c2a91d4e84b0c9a6e15b2c8d40f37"
}

HTTP status codes

StatusMeaningWhat to do
200, 201, 204

It worked

Read the body, if there is one

304

Nothing changed since your ETag

Use your cached copy

400

The request is malformed

Fix the request; check code and errors

401

No key, or a key that doesn't work

Check the Authorization header and the key

403

The key can't do this

Use a key with the right scope

404

Not found for your company

Check the id or SKU

405

Wrong HTTP method

See the Allow header

409

The change clashes with your data

Check code, then decide

412

A precondition failed

Read the resource again, then decide

413

The body is over 1 MB, whether or not you sent Content-Length

Send less

415

The body isn't JSON

Send Content-Type: application/json

422

The JSON body is invalid

Fix the field named in errors

429

Too many requests

Wait Retry-After seconds

500

Something failed on our side

Don't retry; contact support with the request_id

503

Temporarily unavailable

Wait Retry-After seconds, then retry

A 401 carries a WWW-Authenticate: Bearer realm="api.getprice.ai" header, with error="invalid_token" once a key was sent. A 403 carries the same header with error="insufficient_scope" and the missing scope.

Attributes

  • type#string

    Identifies the error: https://api.getprice.ai/errors/ plus code with hyphens. It redirects to the error's row on the Errors page (https://www.getprice.ai/developers/errors).

  • title#string

    A short human-readable name for the error type.

  • status#integer

    The HTTP status code (also in the body).

  • detail#string

    Human-readable explanation for this occurrence.

  • code#string

    Stable machine-readable error code. Open set: new codes may be added, so handle an unknown code by its HTTP status. Codes in this list that no endpoint documents are reserved and not sent today.

    See Error codes

  • request_id#string

    The same value as the X-Request-Id header. Quote it to support.

    Example
    req_7f3c2a91d4e84b0c9a6e15b2c8d40f37
  • errors#array of objects

    Field-level details for validation errors.

    Show child attributesHide child attributes
    • pointer#string

      JSON Pointer into the request body, for example /product_id.

    • parameter#string

      Name of the offending query parameter.

    • detail#string

      What is wrong with this field or parameter.

  • limit#string

    On 429, which limit was hit (for example sustained).

  • retry_after#integer

    On 429, seconds to wait (same as the Retry-After header).

Error codes

CodeStatusMeaningHow to fix
validation_failed400A parameter value is invalid, such as more than 100 sku values or limit=0Fix the value named in errors. Don't retry.
unknown_parameter400The endpoint doesn't take this query parameter, often because of a typoFix the parameter name. Don't retry.
invalid_parameter400A parameter value contains a control characterRemove the character. Don't retry.
cursor_mismatch400The filters or the endpoint changed while you paged with a cursorStart again without a cursor. Don't retry.
invalid_cursor400The cursor is malformed, altered or expiredStart again without a cursor. Don't retry.
unauthenticated401There's no Authorization: Bearer headerSend your key. Don't retry.
invalid_key401detail says The API key is malformed. (format or checksum) or The API key is not valid. (unknown, revoked or expired; we don't say which)Check for copy-paste damage. If the key is intact, an admin can regenerate it in Settings. Don't retry.
insufficient_scope403The key lacks this endpoint's scopeUse a key with that scope. Don't retry.
not_found404There's no such resource for your companyCheck the id or SKU. Don't retry.
product_not_found404product_id isn't one of your own productsUse an id from GET /v1/products. Don't retry.
method_not_allowed405The path doesn't support this HTTP methodUse a method from the Allow header. Don't retry.
sku_on_website409The SKU is on one of your website products, and you tried to link it to a product built from your catalogue. The body's product_id is the website productKeep the SKU on the website product, or link another SKU. Don't retry.
conflict409A write clashed with another changeRead the resource again, then decide. Don't retry.
precondition_failed412You sent If-None-Match: * and the SKU is already linked, or If-Match didn't matchRead the link again, then decide. Don't retry.
payload_too_large413The request body is over 1 MB, whether or not you sent Content-LengthSend a smaller body. Don't retry.
unsupported_media_type415The body isn't application/jsonSet Content-Type: application/json. Don't retry.
validation_failed422The JSON body is invalid, such as a missing product_idFix the field named in errors. Don't retry.
rate_limited429This request costs more units than you have left this minuteWait Retry-After seconds, then retry
internal_error500Something failed on our sideContact support with the request_id. Don't retry.
unavailable503GetPrice can't guarantee correct match data right now, or is too busyWait Retry-After seconds, then retry

For codes not listed here, see Codes you don't recognise.

Check your API key#

Returns details of the API key you're calling with: its name and prefix (never the secret), your company, its scopes and its rate limit. Any valid key can call it, whatever its scopes. Use it to check that your key works.

BASE=https://api.getprice.ai/v1
curl "$BASE/me" \
  -H "Authorization: Bearer $GETPRICE_API_KEY"
import os

import requests

BASE = "https://api.getprice.ai/v1"
KEY = os.environ["GETPRICE_API_KEY"]

resp = requests.get(
    f"{BASE}/me",
    headers={"Authorization": f"Bearer {KEY}"},
    timeout=30,
)
resp.raise_for_status()
me = resp.json()
name = me["company"]["name"]
per_minute = me["limits"]["per_minute"]
print(f"Connected: {name}, {per_minute}/min")
interface Me {
  company: { name: string };
  limits: { per_minute: number };
}

const BASE = "https://api.getprice.ai/v1";
const KEY = process.env.GETPRICE_API_KEY;
const url = `${BASE}/me`;
const res = await fetch(url, {
  headers: { Authorization: `Bearer ${KEY}` },
});
if (!res.ok) {
  throw new Error(`GetPrice returned ${res.status}`);
}
const me = (await res.json()) as Me;
const { name } = me.company;
const perMinute = me.limits.per_minute;
console.log(`Connected: ${name}, ${perMinute}/min`);
<?php
$base = "https://api.getprice.ai/v1";
$key = getenv("GETPRICE_API_KEY");
$ch = curl_init("$base/me");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $key",
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($body === false || $status >= 400) {
    throw new RuntimeException(
        "GetPrice returned $status: $body"
    );
}
$data = json_decode(
    $body, true, flags: JSON_THROW_ON_ERROR
);

printf(
    "Connected: %s, %d/min\n",
    $data["company"]["name"],
    $data["limits"]["per_minute"],
);
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;
using Naming = System.Text.Json.JsonNamingPolicy;

var key = Environment.GetEnvironmentVariable(
    "GETPRICE_API_KEY");
var api = new Uri("https://api.getprice.ai/v1/");
var http = new HttpClient { BaseAddress = api };
http.Timeout = TimeSpan.FromSeconds(30);
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", key);
var json = new JsonSerializerOptions
{
    PropertyNamingPolicy = Naming.SnakeCaseLower,
};

var res = await http.GetAsync("me");
res.EnsureSuccessStatusCode();
var me = await res.Content
    .ReadFromJsonAsync<Me>(json);
var name = me!.Company.Name;
var perMinute = me.Limits.PerMinute;
Console.WriteLine(
    $"Connected: {name}, {perMinute}/min");

record Me(Company Company, Limits Limits);
record Company(string Name);
record Limits(int PerMinute);
Response200
{
  "key": {
    "name": "ERP production",
    "prefix": "k3Xa91Qz",
    "environment": "live"
  },
  "company": {
    "name": "Example Trading (Pty) Ltd"
  },
  "scopes": [
    "catalog:read",
    "matches:read",
    "skus:write"
  ],
  "limits": {
    "per_minute": 120,
    "window_seconds": 60
  }
}

Headers

  • If-None-Match#string

    An ETag from a previous response. If nothing changed you get 304 Not Modified with no body.

Returns

200

The calling key.

  • key#object

    The key you're calling with. Never includes the secret.

    Show child attributesHide child attributes
    • name#string

      The key's name as shown in Settings → API & Integrations.

    • prefix#string

      The public part of the key. Safe to quote to support; identifies the key in logs.

    • environment#string

      live for every key today; there is no test environment yet. test is reserved. Open set.

      One of (more may be added)
      live, test
  • company#object

    The organisation this key belongs to. Every request is scoped to it.

    Show child attributesHide child attributes
    • name#string

      Your organisation's name in GetPrice.

  • scopes#array of strings

    What this key may do. A key created in Settings has all three.

  • limits#object

    This key's rate limit; see the RateLimit headers on every response.

    Show child attributesHide child attributes
    • per_minute#integer

      Rate-limit units per window. Most requests cost 1 unit.

    • window_seconds#integer

      Length of the rate-limit window in seconds.

Errors

  • 400

    The request is malformed: an invalid or unknown query parameter, a bad cursor, more than 100 sku values, or an invalid SKU in the path (empty after trimming or over 100 characters).

  • 401

    No Authorization: Bearer header (unauthenticated), or a key that doesn't work (invalid_key).

  • 429

    This request costs more rate-limit units than you have left.

  • 500

    Something went wrong on our side.

  • 503

    Temporarily unavailable: GetPrice can't guarantee correct match data right now, or the database is saturated.

How errors are shaped

The comparison set object#

Example
{
  "id": "set_x7Kp2Lm9",
  "name": "55-inch 4K UHD Smart TV",
  "sku": "TV-55UHD",
  "own_product": {
    "id": "prd_8fK2mQa1",
    "name": "55-inch 4K UHD Smart TV",
    "url": "https://shop.example.com/product/TV-55UHD",
    "price": {
      "amount": "8999.00",
      "was": null,
      "currency": "ZAR",
      "deal": null
    },
    "last_collected_at": "2026-11-02T04:12:09Z",
    "stale": false,
    "is_catalogue": false
  },
  "competitors": [
    {
      "competitor": {
        "id": "cmp_7RwK4tB9",
        "name": "Kestrel Electronics",
        "domain": "kestrel.example.com"
      },
      "product": {
        "id": "prd_Q2vN9cD4",
        "name": "55\" 4K UHD Smart LED TV",
        "url": "https://kestrel.example.com/tv/55-4k-uhd-smart-led-tv"
      },
      "price": {
        "amount": "8499.00",
        "was": "9499.00",
        "currency": "ZAR",
        "deal": null
      },
      "last_collected_at": "2026-11-02T03:05:11Z",
      "availability": "unknown",
      "status": "active",
      "stale": false,
      "match": {
        "review": "same",
        "reviewed_by": "customer",
        "confidence": null
      }
    },
    {
      "competitor": {
        "id": "cmp_3LqV8nP2",
        "name": "Marula Online",
        "domain": "marula.example.com"
      },
      "product": {
        "id": "prd_Hm3Wc8Kp",
        "name": "55 Inch 4K Ultra HD Smart TV",
        "url": "https://marula.example.com/p/55-inch-4k-ultra-hd-smart-tv"
      },
      "price": {
        "amount": "8999.00",
        "was": null,
        "currency": "ZAR",
        "deal": null
      },
      "last_collected_at": "2026-11-02T03:11:40Z",
      "availability": "unknown",
      "status": "active",
      "stale": false,
      "match": {
        "review": "same",
        "reviewed_by": "getprice",
        "confidence": 0.94
      }
    },
    {
      "competitor": {
        "id": "cmp_9TzM2cX5",
        "name": "Summit Cash & Carry",
        "domain": "summit.example.com"
      },
      "product": {
        "id": "prd_Zt6Pa2Rn",
        "name": "Smart TV 55in 4K UHD",
        "url": "https://summit.example.com/electronics/smart-tv-55in-4k-uhd"
      },
      "price": {
        "amount": "8799.00",
        "was": null,
        "currency": "ZAR",
        "deal": {
          "text": "BUY 2 OR MORE For R 8599.00",
          "type": "tiered_unit",
          "min_qty": 2,
          "unit_price": "8599.00",
          "condition": "none"
        }
      },
      "last_collected_at": "2026-11-02T03:20:05Z",
      "availability": "unknown",
      "status": "active",
      "stale": false,
      "match": {
        "review": "unreviewed",
        "reviewed_by": null,
        "confidence": 0.81
      }
    },
    {
      "competitor": {
        "id": "cmp_2HdR6wJ3",
        "name": "Ironwood Home",
        "domain": "ironwood.example.com"
      },
      "product": {
        "id": "prd_Yc1Ke7Fs",
        "name": "55-inch 4K UHD Smart TV (2025 model)",
        "url": "https://ironwood.example.com/appliances/55-inch-4k-uhd-smart-tv-2025"
      },
      "price": {
        "amount": "7999.00",
        "was": null,
        "currency": "ZAR",
        "deal": null
      },
      "last_collected_at": "2026-10-24T04:31:58Z",
      "availability": "unknown",
      "status": "active",
      "stale": true,
      "match": {
        "review": "with_differences",
        "reviewed_by": "customer",
        "confidence": null
      }
    }
  ],
  "integrity": "ok",
  "updated_at": "2026-11-02T04:14:00Z"
}

Attributes

  • id#string

    Opaque comparison set id.

    Example
    set_x7Kp2Lm9
  • name#string

    The set's name in the dashboard (normally your product's name).

  • sku#stringnullable

    Your SKU for this set, or null if none is linked.

  • own_product#objectnullable

    Your product in this set, or null if the set has no product of yours.

    Show child attributesHide child attributes
    • id#string

      Opaque product id. Stable across URL changes and re-collection.

      Example
      prd_8fK2mQa1
    • name#string

      The product name as your own shop shows it.

    • url#string

      The product page on your own shop. For a product from your uploaded catalogue (is_catalogue: true) this is a fixed GetPrice page, because the product has no page on your shop.

    • price#objectnullable

      Your current price, or null if none has been collected.

      Show child attributesHide child attributes
      • amount#string

        The price a shopper pays now. During a promotion, this is the discounted price. "Cheapest" and "position" in GetPrice always use amount.

        Example
        8999.00
      • was#stringnullable

        The original (pre-discount) price the retailer shows during a promotion, from the same price reading as amount. Sent only when strictly greater than amount; otherwise null (not on promotion).

        Example
        8999.00
      • currency#string

        ISO 4217 code. Always present.

        Example
        ZAR
      • deal#objectnullable

        A multi-buy or member deal the retailer shows next to this price, such as "BUY 2 OR MORE For R 95.00", from the same price reading as amount. null when that reading shows no deal. A deal is never the price: amount stays the price of one item, and "cheapest" and "position" in GetPrice never use it.

        Show child attributesHide child attributes
        • text#string

          The deal exactly as the retailer's website shows it. Always present.

          Example
          BUY 2 OR MORE For R 95.00
        • type#stringnullable

          How GetPrice reads the deal: multi_buy_total (a total for a number of items, "2 for R30"), tiered_unit (a price per item from a quantity, "BUY 2 OR MORE For R 95.00"), buy_x_pay_y ("buy 3, pay for 2"), buy_x_save_pct ("buy 2, save 10%"), buy_x_save_amount ("buy 2, save R10"), member_price (a loyalty or member price) and unparsed (GetPrice kept the text but could not turn it into a price per item; min_qty and unit_price are then null). null when the deal has not been classified. Open set.

          One of (more may be added)
          multi_buy_total, tiered_unit, buy_x_pay_y, buy_x_save_pct, buy_x_save_amount, member_price, unparsed
        • min_qty#integernullable

          The number of items to buy to get the deal. null when the deal names no quantity.

        • unit_price#stringnullable

          The effective price of one item when you buy min_qty under the deal. null for an unparsed deal.

          Example
          8999.00
        • condition#stringnullable

          Who can get the deal: none (every shopper), loyalty (members of the retailer's loyalty programme only) or online_only (online orders only). null when not recorded. Open set.

          One of (more may be added)
          none, loyalty, online_only
    • last_collected_at#timestampnullable

      The last time GetPrice successfully read this product's price, whether or not it changed. Failed reads, and readings rejected by our quality checks, don't move it; you keep the previous good price and its time. It is not "when the price last changed". null when price is null.

      Example
      2026-11-02T04:12:09Z
    • stale#boolean

      true when last_collected_at is older than your refresh schedule's longest normal gap plus 24 hours (for a Monday/Wednesday/Friday schedule: 96 hours), or there is no price. The price is still returned; treat it with care.

    • is_catalogue#boolean

      true when GetPrice built this product from a catalogue you uploaded ("From your catalogue"), not from your online shop. Its url is then a fixed GetPrice page. See Catalogue products.

  • competitors#array of objects

    Every competitor in the set, as the dashboard shows it. [] when there are none.

    Show child attributesHide child attributes
    • competitor#object
      Show child attributesHide child attributes
      • id#string

        Opaque competitor (website) id.

        Example
        cmp_3LqV8nP2
      • name#string

        The competitor's name as shown in the dashboard.

        Example
        Kestrel Electronics
      • domain#string

        The competitor's website host name.

        Example
        kestrel.example.com
    • product#object

      A competitor's listing of the item, as collected from their site.

      Show child attributesHide child attributes
      • id#string

        Opaque product id. Stable across URL changes and re-collection.

        Example
        prd_8fK2mQa1
      • name#string

        The product name as the competitor's page shows it.

      • url#string

        The competitor's product page.

    • price#objectnullable

      The competitor's current price, or null if no valid price is available.

      Show child attributesHide child attributes
      • amount#string

        The price a shopper pays now. During a promotion, this is the discounted price. "Cheapest" and "position" in GetPrice always use amount.

        Example
        8999.00
      • was#stringnullable

        The original (pre-discount) price the retailer shows during a promotion, from the same price reading as amount. Sent only when strictly greater than amount; otherwise null (not on promotion).

        Example
        8999.00
      • currency#string

        ISO 4217 code. Always present.

        Example
        ZAR
      • deal#objectnullable

        A multi-buy or member deal the retailer shows next to this price, such as "BUY 2 OR MORE For R 95.00", from the same price reading as amount. null when that reading shows no deal. A deal is never the price: amount stays the price of one item, and "cheapest" and "position" in GetPrice never use it.

        Show child attributesHide child attributes
        • text#string

          The deal exactly as the retailer's website shows it. Always present.

          Example
          BUY 2 OR MORE For R 95.00
        • type#stringnullable

          How GetPrice reads the deal: multi_buy_total (a total for a number of items, "2 for R30"), tiered_unit (a price per item from a quantity, "BUY 2 OR MORE For R 95.00"), buy_x_pay_y ("buy 3, pay for 2"), buy_x_save_pct ("buy 2, save 10%"), buy_x_save_amount ("buy 2, save R10"), member_price (a loyalty or member price) and unparsed (GetPrice kept the text but could not turn it into a price per item; min_qty and unit_price are then null). null when the deal has not been classified. Open set.

          One of (more may be added)
          multi_buy_total, tiered_unit, buy_x_pay_y, buy_x_save_pct, buy_x_save_amount, member_price, unparsed
        • min_qty#integernullable

          The number of items to buy to get the deal. null when the deal names no quantity.

        • unit_price#stringnullable

          The effective price of one item when you buy min_qty under the deal. null for an unparsed deal.

          Example
          8999.00
        • condition#stringnullable

          Who can get the deal: none (every shopper), loyalty (members of the retailer's loyalty programme only) or online_only (online orders only). null when not recorded. Open set.

          One of (more may be added)
          none, loyalty, online_only
    • last_collected_at#timestampnullable

      The last time GetPrice successfully read this product's price, whether or not it changed. Failed reads, and readings rejected by our quality checks, don't move it; you keep the previous good price and its time. It is not "when the price last changed". null when price is null.

      Example
      2026-11-02T04:12:09Z
    • availability#string

      Stock status on the competitor's site. GetPrice does not collect stock yet, so this is unknown for every listing for now. Other values will appear without notice; treat this as an open set.

      One of (more may be added)
      unknown, in_stock, out_of_stock
    • status#string

      active while the product is listed on the competitor's site. delisted products are only returned with include_delisted=true.

      One of (more may be added)
      active, delisted
    • stale#boolean

      true when last_collected_at is older than your refresh schedule's longest normal gap plus 24 hours (for a Monday/Wednesday/Friday schedule: 96 hours), or there is no price. The price is still returned; treat it with care.

    • match#object

      How this competitor product came to be in the set.

      Show child attributesHide child attributes
      • review#string

        same: confirmed as the same item. with_differences: kept on purpose despite a difference (for example pack size). unreviewed: added to the set but not yet confirmed; GetPrice leaves these out of "cheapest" and "position" in the dashboard. Open set.

        One of (more may be added)
        same, with_differences, unreviewed
      • reviewed_by#stringnullable

        Who confirmed it: customer, one of your own users; getprice, GetPrice's matching team or review process; null, not confirmed by anyone yet. Open set.

        One of (more may be added)
        customer, getprice
      • confidence#numbernullable

        The matcher's confidence from 0 to 1 when a machine match backs this entry, otherwise null.

        Range
        0 to 1
  • integrity#string

    ok: at most one listing per competitor. retailer_conflict: the set holds more than one listing from the same retailer (for example two pack sizes). All of them are returned; treat the set with care, for example take the lowest price per retailer or flag the set for review. Open set.

    One of (more may be added)
    ok, retailer_conflict
  • updated_at#timestamp

    When the set's contents last changed (not on every price read).

    Example
    2026-11-02T04:12:09Z

List comparison sets#

Requires matches:read

Returns your comparison sets: each of your products with every competitor's price and when it was last collected.

Call it in one of two ways:

  • Look up SKUs. Repeat sku for up to 100 of your SKUs: ?sku=TV-55UHD&sku=TEA-RB80-C12. data holds a set for each SKU that has one, and skus gives each SKU's status: found, no_comparison_set or unknown_sku.
  • Sync everything. Leave out sku and follow next_cursor until it is null.

Rate-limit cost: with sku, 1 unit per 25 SKUs (rounded up); without it, 1 unit per 100 of limit (rounded up). Every other endpoint costs 1 unit.

Pack and case codes answer unknown_sku until you link them. GetPrice never converts unit prices into pack prices. Suppressed prices and rejected matches are never returned. Delisted competitor products appear only with include_delisted=true.

BASE=https://api.getprice.ai/v1
curl -G "$BASE/comparison-sets" \
  -H "Authorization: Bearer $GETPRICE_API_KEY" \
  --data-urlencode "sku=TV-55UHD" \
  --data-urlencode "sku=TEA-RB80-C12" \
  --data-urlencode "sku=KTL-17-SS"
import os

import requests

BASE = "https://api.getprice.ai/v1"
KEY = os.environ["GETPRICE_API_KEY"]

resp = requests.get(
    f"{BASE}/comparison-sets",
    params=[
        ("sku", "TV-55UHD"),
        ("sku", "TEA-RB80-C12"),
        ("sku", "KTL-17-SS"),
    ],
    headers={"Authorization": f"Bearer {KEY}"},
    timeout=30,
)
resp.raise_for_status()
page = resp.json()
for entry in page["skus"]:
    print(entry["sku"], entry["status"])
for cset in page["data"]:
    for entry in cset["competitors"]:
        price = entry["price"]
        if price:
            name = entry["competitor"]["name"]
            print(cset["sku"], name, price["amount"])
interface Entry {
  competitor: { name: string };
  price: { amount: string } | null;
}
interface Page {
  data: { sku: string | null; competitors: Entry[] }[];
  skus: { sku: string; status: string }[];
}

const BASE = "https://api.getprice.ai/v1";
const KEY = process.env.GETPRICE_API_KEY;
const params = new URLSearchParams([
  ["sku", "TV-55UHD"],
  ["sku", "TEA-RB80-C12"],
  ["sku", "KTL-17-SS"],
]);
const url = `${BASE}/comparison-sets?${params}`;
const res = await fetch(url, {
  headers: { Authorization: `Bearer ${KEY}` },
});
if (!res.ok) {
  throw new Error(`GetPrice returned ${res.status}`);
}
const page = (await res.json()) as Page;
for (const { sku, status } of page.skus) {
  console.log(sku, status);
}
for (const set of page.data) {
  for (const { competitor, price } of set.competitors) {
    if (!price) continue;
    console.log(set.sku, competitor.name, price.amount);
  }
}
<?php
$base = "https://api.getprice.ai/v1";
$key = getenv("GETPRICE_API_KEY");
// Repeat sku once per SKU.
$skus = ["TV-55UHD", "TEA-RB80-C12", "KTL-17-SS"];
$query = implode("&", array_map(
    fn ($sku) => "sku=" . rawurlencode($sku),
    $skus,
));
$ch = curl_init("$base/comparison-sets?$query");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $key",
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($body === false || $status >= 400) {
    throw new RuntimeException(
        "GetPrice returned $status: $body"
    );
}
$data = json_decode(
    $body, true, flags: JSON_THROW_ON_ERROR
);

foreach ($data["skus"] as $entry) {
    echo $entry["sku"], " ", $entry["status"], "\n";
}
foreach ($data["data"] as $set) {
    foreach ($set["competitors"] as $entry) {
        if ($entry["price"] === null) {
            continue;
        }
        echo $set["sku"], " ",
            $entry["competitor"]["name"], " ",
            $entry["price"]["amount"], "\n";
    }
}
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;
using Naming = System.Text.Json.JsonNamingPolicy;

var key = Environment.GetEnvironmentVariable(
    "GETPRICE_API_KEY");
var api = new Uri("https://api.getprice.ai/v1/");
var http = new HttpClient { BaseAddress = api };
http.Timeout = TimeSpan.FromSeconds(30);
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", key);
var json = new JsonSerializerOptions
{
    PropertyNamingPolicy = Naming.SnakeCaseLower,
};

var res = await http.GetAsync(
    "comparison-sets?sku=TV-55UHD&sku=TEA-RB80-C12"
    + "&sku=KTL-17-SS");
res.EnsureSuccessStatusCode();
var page = await res.Content
    .ReadFromJsonAsync<Page>(json);
foreach (var s in page!.Skus)
    Console.WriteLine($"{s.Sku} {s.Status}");
foreach (var set in page.Data)
    foreach (var e in set.Competitors)
        if (e.Price is { } price)
            Console.WriteLine(
                $"{set.Sku} {e.Competitor.Name} "
                + price.Amount);

record Page(List<CompSet> Data, List<SkuStatus> Skus);
record SkuStatus(string Sku, string Status);
record CompSet(string? Sku, List<Entry> Competitors);
record Entry(Competitor Competitor, Price? Price);
record Competitor(string Name);
record Price(string Amount);
Response200
{
  "data": [
    {
      "id": "set_x7Kp2Lm9",
      "name": "55-inch 4K UHD Smart TV",
      "sku": "TV-55UHD",
      "own_product": {
        "id": "prd_8fK2mQa1",
        "name": "55-inch 4K UHD Smart TV",
        "url": "https://shop.example.com/product/TV-55UHD",
        "price": {
          "amount": "8999.00",
          "was": null,
          "currency": "ZAR",
          "deal": null
        },
        "last_collected_at": "2026-11-02T04:12:09Z",
        "stale": false,
        "is_catalogue": false
      },
      "competitors": [
        {
          "competitor": {
            "id": "cmp_7RwK4tB9",
            "name": "Kestrel Electronics",
            "domain": "kestrel.example.com"
          },
          "product": {
            "id": "prd_Q2vN9cD4",
            "name": "55\" 4K UHD Smart LED TV",
            "url": "https://kestrel.example.com/tv/55-4k-uhd-smart-led-tv"
          },
          "price": {
            "amount": "8499.00",
            "was": "9499.00",
            "currency": "ZAR",
            "deal": null
          },
          "last_collected_at": "2026-11-02T03:05:11Z",
          "availability": "unknown",
          "status": "active",
          "stale": false,
          "match": {
            "review": "same",
            "reviewed_by": "customer",
            "confidence": null
          }
        },
        {
          "competitor": {
            "id": "cmp_3LqV8nP2",
            "name": "Marula Online",
            "domain": "marula.example.com"
          },
          "product": {
            "id": "prd_Hm3Wc8Kp",
            "name": "55 Inch 4K Ultra HD Smart TV",
            "url": "https://marula.example.com/p/55-inch-4k-ultra-hd-smart-tv"
          },
          "price": {
            "amount": "8999.00",
            "was": null,
            "currency": "ZAR",
            "deal": null
          },
          "last_collected_at": "2026-11-02T03:11:40Z",
          "availability": "unknown",
          "status": "active",
          "stale": false,
          "match": {
            "review": "same",
            "reviewed_by": "getprice",
            "confidence": 0.94
          }
        },
        {
          "competitor": {
            "id": "cmp_9TzM2cX5",
            "name": "Summit Cash & Carry",
            "domain": "summit.example.com"
          },
          "product": {
            "id": "prd_Zt6Pa2Rn",
            "name": "Smart TV 55in 4K UHD",
            "url": "https://summit.example.com/electronics/smart-tv-55in-4k-uhd"
          },
          "price": {
            "amount": "8799.00",
            "was": null,
            "currency": "ZAR",
            "deal": {
              "text": "BUY 2 OR MORE For R 8599.00",
              "type": "tiered_unit",
              "min_qty": 2,
              "unit_price": "8599.00",
              "condition": "none"
            }
          },
          "last_collected_at": "2026-11-02T03:20:05Z",
          "availability": "unknown",
          "status": "active",
          "stale": false,
          "match": {
            "review": "unreviewed",
            "reviewed_by": null,
            "confidence": 0.81
          }
        },
        {
          "competitor": {
            "id": "cmp_2HdR6wJ3",
            "name": "Ironwood Home",
            "domain": "ironwood.example.com"
          },
          "product": {
            "id": "prd_Yc1Ke7Fs",
            "name": "55-inch 4K UHD Smart TV (2025 model)",
            "url": "https://ironwood.example.com/appliances/55-inch-4k-uhd-smart-tv-2025"
          },
          "price": {
            "amount": "7999.00",
            "was": null,
            "currency": "ZAR",
            "deal": null
          },
          "last_collected_at": "2026-10-24T04:31:58Z",
          "availability": "unknown",
          "status": "active",
          "stale": true,
          "match": {
            "review": "with_differences",
            "reviewed_by": "customer",
            "confidence": null
          }
        }
      ],
      "integrity": "ok",
      "updated_at": "2026-11-02T04:14:00Z"
    }
  ],
  "next_cursor": null,
  "skus": [
    {
      "sku": "TV-55UHD",
      "status": "found",
      "set_id": "set_x7Kp2Lm9",
      "product_id": "prd_8fK2mQa1"
    },
    {
      "sku": "KTL-17-SS",
      "status": "no_comparison_set",
      "set_id": null,
      "product_id": "prd_Zt41Hq6m"
    },
    {
      "sku": "TEA-RB80-C12",
      "status": "unknown_sku",
      "set_id": null,
      "product_id": null
    }
  ]
}

Query parameters

  • sku#array of strings

    Your SKU. Repeat the parameter for several SKUs (?sku=A&sku=B), up to 100. Commas are part of the SKU, not separators. Matching ignores case and surrounding spaces; every other character (including leading zeros) counts: 00981A and 981A are different SKUs.

    Max items
    100
  • reviewed_by#string

    customer returns only competitors your own users have confirmed. Omit for every competitor in the set.

    One of
    customer
  • include_delisted#boolean

    true also returns competitor products that are no longer listed (status: delisted).

    Default
    false
  • limit#integer

    Items per page. Default 100. Values above 500 are treated as 500.

    Default
    100
  • cursor#string

    The next_cursor from the previous page. Opaque: pass it back unchanged, together with the same filters, on the same endpoint, as the first request (otherwise 400 cursor_mismatch).

Headers

  • If-None-Match#string

    An ETag from a previous response. If nothing changed you get 304 Not Modified with no body.

Returns

200

A page of comparison sets.

  • The comparison sets on this page, in a stable order.

  • next_cursor#stringnullable

    Pass as cursor to get the next page. null on the last page.

  • skus#array of objects

    Only when you filter by sku, and only on the first page: one entry per SKU you sent, in the order you sent them, saying what happened to it.

    Show child attributesHide child attributes
    • sku#string

      The SKU as you sent it (trimmed).

      Example
      TV-55UHD
    • status#string

      found: linked to your product, which has a comparison set (in data). no_comparison_set: linked to your product, but no comparison set has been built for it yet. unknown_sku: not linked to any of your products. The stock codes on your online shop are pre-loaded, so this is usually a pack, case or internal code; link it with PUT /v1/sku-mappings/{sku}. Open set.

      One of (more may be added)
      found, no_comparison_set, unknown_sku
    • set_id#stringnullable

      The comparison set in data when status is found, otherwise null.

      Example
      set_x7Kp2Lm9
    • product_id#stringnullable

      The product the SKU is linked to, or null for unknown_sku.

      Example
      prd_8fK2mQa1

Errors

  • 400

    The request is malformed: an invalid or unknown query parameter, a bad cursor, more than 100 sku values, or an invalid SKU in the path (empty after trimming or over 100 characters).

  • 401

    No Authorization: Bearer header (unauthenticated), or a key that doesn't work (invalid_key).

  • 403

    The key is valid but lacks the scope this endpoint needs.

  • 429

    This request costs more rate-limit units than you have left.

  • 500

    Something went wrong on our side.

  • 503

    Temporarily unavailable: GetPrice can't guarantee correct match data right now, or the database is saturated.

How errors are shaped

Retrieve a comparison set#

Requires matches:read

Returns the comparison set with the given id. If the set was merged into another one, you get the surviving set, and its id differs from the one you asked for.

BASE=https://api.getprice.ai/v1
curl "$BASE/comparison-sets/set_x7Kp2Lm9" \
  -H "Authorization: Bearer $GETPRICE_API_KEY"
import os

import requests

BASE = "https://api.getprice.ai/v1"
KEY = os.environ["GETPRICE_API_KEY"]

resp = requests.get(
    f"{BASE}/comparison-sets/set_x7Kp2Lm9",
    headers={"Authorization": f"Bearer {KEY}"},
    timeout=30,
)
resp.raise_for_status()
cset = resp.json()
for entry in cset["competitors"]:
    price = entry["price"]
    amount = f"R{price['amount']}" if price else "-"
    name = entry["competitor"]["name"]
    print(name, amount, entry["last_collected_at"])
interface Entry {
  competitor: { name: string };
  price: { amount: string } | null;
  last_collected_at: string | null;
}

const BASE = "https://api.getprice.ai/v1";
const KEY = process.env.GETPRICE_API_KEY;
const url = `${BASE}/comparison-sets/set_x7Kp2Lm9`;
const res = await fetch(url, {
  headers: { Authorization: `Bearer ${KEY}` },
});
if (!res.ok) {
  throw new Error(`GetPrice returned ${res.status}`);
}
const set = (await res.json()) as {
  competitors: Entry[];
};
for (const entry of set.competitors) {
  const { price } = entry;
  const amount = price ? `R${price.amount}` : "-";
  const name = entry.competitor.name;
  console.log(name, amount, entry.last_collected_at);
}
<?php
$base = "https://api.getprice.ai/v1";
$key = getenv("GETPRICE_API_KEY");
$ch = curl_init("$base/comparison-sets/set_x7Kp2Lm9");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $key",
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($body === false || $status >= 400) {
    throw new RuntimeException(
        "GetPrice returned $status: $body"
    );
}
$data = json_decode(
    $body, true, flags: JSON_THROW_ON_ERROR
);

foreach ($data["competitors"] as $entry) {
    $price = $entry["price"];
    $amount = $price ? "R" . $price["amount"] : "-";
    echo $entry["competitor"]["name"], " ", $amount,
        " ", $entry["last_collected_at"], "\n";
}
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;
using Naming = System.Text.Json.JsonNamingPolicy;

var key = Environment.GetEnvironmentVariable(
    "GETPRICE_API_KEY");
var api = new Uri("https://api.getprice.ai/v1/");
var http = new HttpClient { BaseAddress = api };
http.Timeout = TimeSpan.FromSeconds(30);
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", key);
var json = new JsonSerializerOptions
{
    PropertyNamingPolicy = Naming.SnakeCaseLower,
};

var res = await http.GetAsync(
    "comparison-sets/set_x7Kp2Lm9");
res.EnsureSuccessStatusCode();
var set = await res.Content
    .ReadFromJsonAsync<CompSet>(json);
foreach (var e in set!.Competitors)
{
    var amount = e.Price is null
        ? "-" : $"R{e.Price.Amount}";
    var name = e.Competitor.Name;
    Console.WriteLine(
        $"{name} {amount} {e.LastCollectedAt}");
}

record CompSet(List<Entry> Competitors);
record Entry(
    Competitor Competitor,
    Price? Price,
    string? LastCollectedAt);
record Competitor(string Name);
record Price(string Amount);
Response200
{
  "id": "set_x7Kp2Lm9",
  "name": "55-inch 4K UHD Smart TV",
  "sku": "TV-55UHD",
  "own_product": {
    "id": "prd_8fK2mQa1",
    "name": "55-inch 4K UHD Smart TV",
    "url": "https://shop.example.com/product/TV-55UHD",
    "price": {
      "amount": "8999.00",
      "was": null,
      "currency": "ZAR",
      "deal": null
    },
    "last_collected_at": "2026-11-02T04:12:09Z",
    "stale": false,
    "is_catalogue": false
  },
  "competitors": [
    {
      "competitor": {
        "id": "cmp_7RwK4tB9",
        "name": "Kestrel Electronics",
        "domain": "kestrel.example.com"
      },
      "product": {
        "id": "prd_Q2vN9cD4",
        "name": "55\" 4K UHD Smart LED TV",
        "url": "https://kestrel.example.com/tv/55-4k-uhd-smart-led-tv"
      },
      "price": {
        "amount": "8499.00",
        "was": "9499.00",
        "currency": "ZAR",
        "deal": null
      },
      "last_collected_at": "2026-11-02T03:05:11Z",
      "availability": "unknown",
      "status": "active",
      "stale": false,
      "match": {
        "review": "same",
        "reviewed_by": "customer",
        "confidence": null
      }
    },
    {
      "competitor": {
        "id": "cmp_3LqV8nP2",
        "name": "Marula Online",
        "domain": "marula.example.com"
      },
      "product": {
        "id": "prd_Hm3Wc8Kp",
        "name": "55 Inch 4K Ultra HD Smart TV",
        "url": "https://marula.example.com/p/55-inch-4k-ultra-hd-smart-tv"
      },
      "price": {
        "amount": "8999.00",
        "was": null,
        "currency": "ZAR",
        "deal": null
      },
      "last_collected_at": "2026-11-02T03:11:40Z",
      "availability": "unknown",
      "status": "active",
      "stale": false,
      "match": {
        "review": "same",
        "reviewed_by": "getprice",
        "confidence": 0.94
      }
    },
    {
      "competitor": {
        "id": "cmp_9TzM2cX5",
        "name": "Summit Cash & Carry",
        "domain": "summit.example.com"
      },
      "product": {
        "id": "prd_Zt6Pa2Rn",
        "name": "Smart TV 55in 4K UHD",
        "url": "https://summit.example.com/electronics/smart-tv-55in-4k-uhd"
      },
      "price": {
        "amount": "8799.00",
        "was": null,
        "currency": "ZAR",
        "deal": {
          "text": "BUY 2 OR MORE For R 8599.00",
          "type": "tiered_unit",
          "min_qty": 2,
          "unit_price": "8599.00",
          "condition": "none"
        }
      },
      "last_collected_at": "2026-11-02T03:20:05Z",
      "availability": "unknown",
      "status": "active",
      "stale": false,
      "match": {
        "review": "unreviewed",
        "reviewed_by": null,
        "confidence": 0.81
      }
    },
    {
      "competitor": {
        "id": "cmp_2HdR6wJ3",
        "name": "Ironwood Home",
        "domain": "ironwood.example.com"
      },
      "product": {
        "id": "prd_Yc1Ke7Fs",
        "name": "55-inch 4K UHD Smart TV (2025 model)",
        "url": "https://ironwood.example.com/appliances/55-inch-4k-uhd-smart-tv-2025"
      },
      "price": {
        "amount": "7999.00",
        "was": null,
        "currency": "ZAR",
        "deal": null
      },
      "last_collected_at": "2026-10-24T04:31:58Z",
      "availability": "unknown",
      "status": "active",
      "stale": true,
      "match": {
        "review": "with_differences",
        "reviewed_by": "customer",
        "confidence": null
      }
    }
  ],
  "integrity": "ok",
  "updated_at": "2026-11-02T04:14:00Z"
}

Path parameters

  • set_id#stringRequired

    The set id, for example set_x7Kp2Lm9.

    Example
    set_x7Kp2Lm9

Query parameters

  • reviewed_by#string

    customer returns only competitors your own users have confirmed. Omit for every competitor in the set.

    One of
    customer
  • include_delisted#boolean

    true also returns competitor products that are no longer listed (status: delisted).

    Default
    false

Headers

  • If-None-Match#string

    An ETag from a previous response. If nothing changed you get 304 Not Modified with no body.

Returns

200

The comparison set.

Returns the comparison set object.

Errors

  • 400

    The request is malformed: an invalid or unknown query parameter, a bad cursor, more than 100 sku values, or an invalid SKU in the path (empty after trimming or over 100 characters).

  • 401

    No Authorization: Bearer header (unauthenticated), or a key that doesn't work (invalid_key).

  • 403

    The key is valid but lacks the scope this endpoint needs.

  • 404

    Not found for your company.

  • 429

    This request costs more rate-limit units than you have left.

  • 500

    Something went wrong on our side.

  • 503

    Temporarily unavailable: GetPrice can't guarantee correct match data right now, or the database is saturated.

How errors are shaped

The product object#

Example
{
  "id": "prd_Lp4sT1x9",
  "name": "18V Cordless Hammer Drill Kit, 2 x 2.0Ah Batteries",
  "url": "https://shop.example.com/product/18v-cordless-hammer-drill-kit",
  "skus": [],
  "comparison_set_id": "set_R4m8wQe2",
  "price": {
    "amount": "2499.00",
    "was": "2799.00",
    "currency": "ZAR",
    "deal": null
  },
  "last_collected_at": "2026-11-02T04:12:31Z",
  "status": "active",
  "is_catalogue": false,
  "replaced_from": null
}

Attributes

  • id#string

    Opaque product id. Stable across URL changes and re-collection.

    Example
    prd_8fK2mQa1
  • name#string

    The product name as your own shop shows it.

  • url#string

    The product page on your own shop. For a product from your uploaded catalogue (is_catalogue: true) this is a fixed GetPrice page, because the product has no page on your shop.

  • skus#array of strings

    Every SKU you have linked to this product. [] when none.

  • comparison_set_id#stringnullable

    The comparison set this product sits in, or null if it is not in one yet.

    Example
    set_x7Kp2Lm9
  • price#objectnullable

    Your current price, or null if none has been collected.

    Show child attributesHide child attributes
    • amount#string

      The price a shopper pays now. During a promotion, this is the discounted price. "Cheapest" and "position" in GetPrice always use amount.

      Example
      8999.00
    • was#stringnullable

      The original (pre-discount) price the retailer shows during a promotion, from the same price reading as amount. Sent only when strictly greater than amount; otherwise null (not on promotion).

      Example
      8999.00
    • currency#string

      ISO 4217 code. Always present.

      Example
      ZAR
    • deal#objectnullable

      A multi-buy or member deal the retailer shows next to this price, such as "BUY 2 OR MORE For R 95.00", from the same price reading as amount. null when that reading shows no deal. A deal is never the price: amount stays the price of one item, and "cheapest" and "position" in GetPrice never use it.

      Show child attributesHide child attributes
      • text#string

        The deal exactly as the retailer's website shows it. Always present.

        Example
        BUY 2 OR MORE For R 95.00
      • type#stringnullable

        How GetPrice reads the deal: multi_buy_total (a total for a number of items, "2 for R30"), tiered_unit (a price per item from a quantity, "BUY 2 OR MORE For R 95.00"), buy_x_pay_y ("buy 3, pay for 2"), buy_x_save_pct ("buy 2, save 10%"), buy_x_save_amount ("buy 2, save R10"), member_price (a loyalty or member price) and unparsed (GetPrice kept the text but could not turn it into a price per item; min_qty and unit_price are then null). null when the deal has not been classified. Open set.

        One of (more may be added)
        multi_buy_total, tiered_unit, buy_x_pay_y, buy_x_save_pct, buy_x_save_amount, member_price, unparsed
      • min_qty#integernullable

        The number of items to buy to get the deal. null when the deal names no quantity.

      • unit_price#stringnullable

        The effective price of one item when you buy min_qty under the deal. null for an unparsed deal.

        Example
        8999.00
      • condition#stringnullable

        Who can get the deal: none (every shopper), loyalty (members of the retailer's loyalty programme only) or online_only (online orders only). null when not recorded. Open set.

        One of (more may be added)
        none, loyalty, online_only
  • last_collected_at#timestampnullable

    The last time GetPrice successfully read this product's price; null when price is null.

    Example
    2026-11-02T04:12:09Z
  • status#string

    active, or delisted when the product is no longer on your site (only with include_delisted=true). Open set.

    One of (more may be added)
    active, delisted
  • is_catalogue#boolean

    true when GetPrice built this product from a catalogue you uploaded ("From your catalogue"), not from your online shop. Its url is then a fixed GetPrice page. See Catalogue products.

  • replaced_from#stringnullable

    The id you asked for, when it belonged to a catalogue product that your website now sells and this is the website product that replaced it (GET /v1/products/{product_id} only). Store id in its place. null everywhere else. See Catalogue products.

    Example
    prd_8fK2mQa1

List your products#

Requires catalog:read

Returns your own products, as GetPrice collects them from your online shop. Search by name with q, and add unmapped=true to find products with no SKU linked. That gives you the prd_… id to link with PUT /v1/sku-mappings/{sku}. Filters combine.

BASE=https://api.getprice.ai/v1
curl -G "$BASE/products" \
  -H "Authorization: Bearer $GETPRICE_API_KEY" \
  --data-urlencode "q=drill" \
  --data-urlencode "unmapped=true"
import os

import requests

BASE = "https://api.getprice.ai/v1"
KEY = os.environ["GETPRICE_API_KEY"]

resp = requests.get(
    f"{BASE}/products",
    params=[("q", "drill"), ("unmapped", "true")],
    headers={"Authorization": f"Bearer {KEY}"},
    timeout=30,
)
resp.raise_for_status()
for product in resp.json()["data"]:
    print(product["id"], product["name"])
interface Product {
  id: string;
  name: string;
}

const BASE = "https://api.getprice.ai/v1";
const KEY = process.env.GETPRICE_API_KEY;
const params = new URLSearchParams([
  ["q", "drill"],
  ["unmapped", "true"],
]);
const url = `${BASE}/products?${params}`;
const res = await fetch(url, {
  headers: { Authorization: `Bearer ${KEY}` },
});
if (!res.ok) {
  throw new Error(`GetPrice returned ${res.status}`);
}
const page = (await res.json()) as {
  data: Product[];
};
for (const product of page.data) {
  console.log(product.id, product.name);
}
<?php
$base = "https://api.getprice.ai/v1";
$key = getenv("GETPRICE_API_KEY");
$query = http_build_query([
    "q" => "drill",
    "unmapped" => "true",
]);
$ch = curl_init("$base/products?$query");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $key",
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($body === false || $status >= 400) {
    throw new RuntimeException(
        "GetPrice returned $status: $body"
    );
}
$data = json_decode(
    $body, true, flags: JSON_THROW_ON_ERROR
);

foreach ($data["data"] as $product) {
    echo $product["id"], " ", $product["name"], "\n";
}
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;
using Naming = System.Text.Json.JsonNamingPolicy;

var key = Environment.GetEnvironmentVariable(
    "GETPRICE_API_KEY");
var api = new Uri("https://api.getprice.ai/v1/");
var http = new HttpClient { BaseAddress = api };
http.Timeout = TimeSpan.FromSeconds(30);
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", key);
var json = new JsonSerializerOptions
{
    PropertyNamingPolicy = Naming.SnakeCaseLower,
};

var res = await http.GetAsync(
    "products?q=drill&unmapped=true");
res.EnsureSuccessStatusCode();
var page = await res.Content
    .ReadFromJsonAsync<Page>(json);
foreach (var p in page!.Data)
    Console.WriteLine($"{p.Id} {p.Name}");

record Page(List<Product> Data);
record Product(string Id, string Name);
Response200
{
  "data": [
    {
      "id": "prd_Lp4sT1x9",
      "name": "18V Cordless Hammer Drill Kit, 2 x 2.0Ah Batteries",
      "url": "https://shop.example.com/product/18v-cordless-hammer-drill-kit",
      "skus": [],
      "comparison_set_id": "set_R4m8wQe2",
      "price": {
        "amount": "2499.00",
        "was": "2799.00",
        "currency": "ZAR",
        "deal": null
      },
      "last_collected_at": "2026-11-02T04:12:31Z",
      "status": "active",
      "is_catalogue": false,
      "replaced_from": null
    }
  ],
  "next_cursor": null
}

Query parameters

  • sku#array of strings

    Your SKU. Repeat the parameter for several SKUs (?sku=A&sku=B), up to 100. Commas are part of the SKU, not separators. Matching ignores case and surrounding spaces; every other character (including leading zeros) counts: 00981A and 981A are different SKUs.

    Max items
    100
  • q#string

    Case-insensitive substring of the product name.

  • unmapped#boolean

    true returns only products with no SKU linked.

    Default
    false
  • include_delisted#boolean

    true also returns products no longer on your site (status: delisted).

    Default
    false
  • limit#integer

    Items per page. Default 100. Values above 500 are treated as 500.

    Default
    100
  • cursor#string

    The next_cursor from the previous page. Opaque: pass it back unchanged, together with the same filters, on the same endpoint, as the first request (otherwise 400 cursor_mismatch).

Headers

  • If-None-Match#string

    An ETag from a previous response. If nothing changed you get 304 Not Modified with no body.

Returns

200

A page of products.

  • Your products on this page, in a stable order.

  • next_cursor#stringnullable

    Pass as cursor to get the next page. null on the last page.

Errors

  • 400

    The request is malformed: an invalid or unknown query parameter, a bad cursor, more than 100 sku values, or an invalid SKU in the path (empty after trimming or over 100 characters).

  • 401

    No Authorization: Bearer header (unauthenticated), or a key that doesn't work (invalid_key).

  • 403

    The key is valid but lacks the scope this endpoint needs.

  • 429

    This request costs more rate-limit units than you have left.

  • 500

    Something went wrong on our side.

  • 503

    Temporarily unavailable: GetPrice can't guarantee correct match data right now, or the database is saturated.

How errors are shaped

Retrieve a product#

Requires catalog:read

Returns one of your own products. A competitor's product id, or an id from another company, returns 404.

When a product built from your uploaded catalogue is taken over by the same product on your website, its old id keeps working: the response is the website product, with that product's id and with replaced_from set to the id you asked for. It is not a redirect. Store the new id. If the website product is no longer one of yours, the old id returns 404.

BASE=https://api.getprice.ai/v1
curl "$BASE/products/prd_8fK2mQa1" \
  -H "Authorization: Bearer $GETPRICE_API_KEY"
import os

import requests

BASE = "https://api.getprice.ai/v1"
KEY = os.environ["GETPRICE_API_KEY"]

resp = requests.get(
    f"{BASE}/products/prd_8fK2mQa1",
    headers={"Authorization": f"Bearer {KEY}"},
    timeout=30,
)
resp.raise_for_status()
product = resp.json()
price = product["price"]
amount = f"R{price['amount']}" if price else "-"
print(product["name"], amount)
interface Product {
  name: string;
  price: { amount: string } | null;
}

const BASE = "https://api.getprice.ai/v1";
const KEY = process.env.GETPRICE_API_KEY;
const url = `${BASE}/products/prd_8fK2mQa1`;
const res = await fetch(url, {
  headers: { Authorization: `Bearer ${KEY}` },
});
if (!res.ok) {
  throw new Error(`GetPrice returned ${res.status}`);
}
const product = (await res.json()) as Product;
const { price } = product;
const amount = price ? `R${price.amount}` : "-";
console.log(product.name, amount);
<?php
$base = "https://api.getprice.ai/v1";
$key = getenv("GETPRICE_API_KEY");
$ch = curl_init("$base/products/prd_8fK2mQa1");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $key",
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($body === false || $status >= 400) {
    throw new RuntimeException(
        "GetPrice returned $status: $body"
    );
}
$data = json_decode(
    $body, true, flags: JSON_THROW_ON_ERROR
);

$price = $data["price"];
$amount = $price ? "R" . $price["amount"] : "-";
echo $data["name"], " ", $amount, "\n";
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;
using Naming = System.Text.Json.JsonNamingPolicy;

var key = Environment.GetEnvironmentVariable(
    "GETPRICE_API_KEY");
var api = new Uri("https://api.getprice.ai/v1/");
var http = new HttpClient { BaseAddress = api };
http.Timeout = TimeSpan.FromSeconds(30);
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", key);
var json = new JsonSerializerOptions
{
    PropertyNamingPolicy = Naming.SnakeCaseLower,
};

var res = await http.GetAsync("products/prd_8fK2mQa1");
res.EnsureSuccessStatusCode();
var product = await res.Content
    .ReadFromJsonAsync<Product>(json);
var amount = product!.Price is null
    ? "-" : $"R{product.Price.Amount}";
Console.WriteLine($"{product.Name} {amount}");

record Product(string Name, Price? Price);
record Price(string Amount);
Response200
{
  "id": "prd_8fK2mQa1",
  "name": "55-inch 4K UHD Smart TV",
  "url": "https://shop.example.com/product/TV-55UHD",
  "skus": [
    "TV-55UHD"
  ],
  "comparison_set_id": "set_x7Kp2Lm9",
  "price": {
    "amount": "8999.00",
    "was": null,
    "currency": "ZAR",
    "deal": null
  },
  "last_collected_at": "2026-11-02T04:12:09Z",
  "status": "active",
  "is_catalogue": false,
  "replaced_from": null
}

Path parameters

  • product_id#stringRequired

    The product id, for example prd_8fK2mQa1.

    Example
    prd_8fK2mQa1

Headers

  • If-None-Match#string

    An ETag from a previous response. If nothing changed you get 304 Not Modified with no body.

Returns

200

The product.

Returns the product object.

Errors

  • 400

    The request is malformed: an invalid or unknown query parameter, a bad cursor, more than 100 sku values, or an invalid SKU in the path (empty after trimming or over 100 characters).

  • 401

    No Authorization: Bearer header (unauthenticated), or a key that doesn't work (invalid_key).

  • 403

    The key is valid but lacks the scope this endpoint needs.

  • 404

    Not found for your company.

  • 429

    This request costs more rate-limit units than you have left.

  • 500

    Something went wrong on our side.

  • 503

    Temporarily unavailable: GetPrice can't guarantee correct match data right now, or the database is saturated.

How errors are shaped

The competitor object#

Example
{
  "id": "cmp_3LqV8nP2",
  "name": "Marula Online",
  "domain": "marula.example.com",
  "url": "https://marula.example.com"
}

Attributes

  • id#string

    Opaque competitor (website) id.

    Example
    cmp_3LqV8nP2
  • name#string

    The competitor's name as shown in the dashboard.

    Example
    Kestrel Electronics
  • domain#string

    The competitor's website host name.

    Example
    kestrel.example.com
  • url#string

    The competitor's website.

    Example
    https://kestrel.example.com

List competitors#

Requires catalog:read

Returns the competitor websites GetPrice collects prices from for you.

BASE=https://api.getprice.ai/v1
curl "$BASE/competitors" \
  -H "Authorization: Bearer $GETPRICE_API_KEY"
import os

import requests

BASE = "https://api.getprice.ai/v1"
KEY = os.environ["GETPRICE_API_KEY"]

resp = requests.get(
    f"{BASE}/competitors",
    headers={"Authorization": f"Bearer {KEY}"},
    timeout=30,
)
resp.raise_for_status()
for c in resp.json()["data"]:
    print(c["id"], c["name"], c["domain"])
interface Competitor {
  id: string;
  name: string;
  domain: string;
}

const BASE = "https://api.getprice.ai/v1";
const KEY = process.env.GETPRICE_API_KEY;
const url = `${BASE}/competitors`;
const res = await fetch(url, {
  headers: { Authorization: `Bearer ${KEY}` },
});
if (!res.ok) {
  throw new Error(`GetPrice returned ${res.status}`);
}
const page = (await res.json()) as {
  data: Competitor[];
};
for (const { id, name, domain } of page.data) {
  console.log(id, name, domain);
}
<?php
$base = "https://api.getprice.ai/v1";
$key = getenv("GETPRICE_API_KEY");
$ch = curl_init("$base/competitors");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $key",
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($body === false || $status >= 400) {
    throw new RuntimeException(
        "GetPrice returned $status: $body"
    );
}
$data = json_decode(
    $body, true, flags: JSON_THROW_ON_ERROR
);

foreach ($data["data"] as $c) {
    echo $c["id"], " ", $c["name"], " ",
        $c["domain"], "\n";
}
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;
using Naming = System.Text.Json.JsonNamingPolicy;

var key = Environment.GetEnvironmentVariable(
    "GETPRICE_API_KEY");
var api = new Uri("https://api.getprice.ai/v1/");
var http = new HttpClient { BaseAddress = api };
http.Timeout = TimeSpan.FromSeconds(30);
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", key);
var json = new JsonSerializerOptions
{
    PropertyNamingPolicy = Naming.SnakeCaseLower,
};

var res = await http.GetAsync("competitors");
res.EnsureSuccessStatusCode();
var page = await res.Content
    .ReadFromJsonAsync<Page>(json);
foreach (var c in page!.Data)
    Console.WriteLine($"{c.Id} {c.Name} {c.Domain}");

record Page(List<Competitor> Data);
record Competitor(
    string Id,
    string Name,
    string Domain);
Response200
{
  "data": [
    {
      "id": "cmp_3LqV8nP2",
      "name": "Marula Online",
      "domain": "marula.example.com",
      "url": "https://marula.example.com"
    },
    {
      "id": "cmp_7RwK4tB9",
      "name": "Kestrel Electronics",
      "domain": "kestrel.example.com",
      "url": "https://kestrel.example.com"
    },
    {
      "id": "cmp_9TzM2cX5",
      "name": "Summit Cash & Carry",
      "domain": "summit.example.com",
      "url": "https://summit.example.com"
    },
    {
      "id": "cmp_2HdR6wJ3",
      "name": "Ironwood Home",
      "domain": "ironwood.example.com",
      "url": "https://ironwood.example.com"
    }
  ],
  "next_cursor": null
}

Query parameters

  • limit#integer

    Items per page. Default 100. Values above 500 are treated as 500.

    Default
    100
  • cursor#string

    The next_cursor from the previous page. Opaque: pass it back unchanged, together with the same filters, on the same endpoint, as the first request (otherwise 400 cursor_mismatch).

Headers

  • If-None-Match#string

    An ETag from a previous response. If nothing changed you get 304 Not Modified with no body.

Returns

200

A page of competitors.

  • The competitors on this page, in a stable order.

  • next_cursor#stringnullable

    Pass as cursor to get the next page. null on the last page.

Errors

  • 400

    The request is malformed: an invalid or unknown query parameter, a bad cursor, more than 100 sku values, or an invalid SKU in the path (empty after trimming or over 100 characters).

  • 401

    No Authorization: Bearer header (unauthenticated), or a key that doesn't work (invalid_key).

  • 403

    The key is valid but lacks the scope this endpoint needs.

  • 429

    This request costs more rate-limit units than you have left.

  • 500

    Something went wrong on our side.

  • 503

    Temporarily unavailable: GetPrice can't guarantee correct match data right now, or the database is saturated.

How errors are shaped

The SKU mapping object#

A link from your SKU to exactly one target: one of your products (product_id) or, for a comparison set with no product of yours, the set itself (comparison_set_id). Exactly one of the two is non-null. Links you make with PUT always target a product.

Example
{
  "sku": "AC-12K-INV",
  "product_id": null,
  "comparison_set_id": "set_Wq3NdT5v",
  "source": "list_sku",
  "created_at": "2026-11-01T16:20:00Z",
  "updated_at": "2026-11-01T16:20:00Z"
}

Attributes

  • sku#string

    Your SKU as stored (trimmed).

    Example
    TV-55UHD
  • product_id#stringnullable

    The linked product, or null when the SKU is linked to a comparison set instead.

    Example
    prd_8fK2mQa1
  • comparison_set_id#stringnullable

    The linked comparison set when it has no product of yours (set up by GetPrice), otherwise null. A PUT to such a SKU replaces the link with a product link.

    Example
    set_x7Kp2Lm9
  • source#string

    How the link was made: api (created through this API), site_sku (the code read from your own website), list_sku (linked in the GetPrice dashboard), import and settings_upload (loaded from a file by GetPrice). Open set.

    One of (more may be added)
    api, list_sku, site_sku, import, settings_upload
  • created_at#timestamp

    RFC 3339, UTC, Z suffix.

    Example
    2026-11-02T04:12:09Z
  • updated_at#timestamp

    RFC 3339, UTC, Z suffix.

    Example
    2026-11-02T04:12:09Z

List SKU mappings#

Requires catalog:read

Returns every SKU link you have, ordered by SKU.

BASE=https://api.getprice.ai/v1
curl -G "$BASE/sku-mappings" \
  -H "Authorization: Bearer $GETPRICE_API_KEY" \
  --data-urlencode "limit=500"
import os

import requests

BASE = "https://api.getprice.ai/v1"
KEY = os.environ["GETPRICE_API_KEY"]

resp = requests.get(
    f"{BASE}/sku-mappings",
    params=[("limit", "500")],
    headers={"Authorization": f"Bearer {KEY}"},
    timeout=30,
)
resp.raise_for_status()
page = resp.json()
for m in page["data"]:
    target = m["product_id"] or m["comparison_set_id"]
    print(m["sku"], target)
# More? Send page["next_cursor"] as cursor.
interface SkuMapping {
  sku: string;
  product_id: string | null;
  comparison_set_id: string | null;
}

const BASE = "https://api.getprice.ai/v1";
const KEY = process.env.GETPRICE_API_KEY;
const params = new URLSearchParams([
  ["limit", "500"],
]);
const url = `${BASE}/sku-mappings?${params}`;
const res = await fetch(url, {
  headers: { Authorization: `Bearer ${KEY}` },
});
if (!res.ok) {
  throw new Error(`GetPrice returned ${res.status}`);
}
const page = (await res.json()) as {
  data: SkuMapping[];
  next_cursor: string | null;
};
for (const m of page.data) {
  const target = m.product_id ?? m.comparison_set_id;
  console.log(m.sku, target);
}
// More? Send page.next_cursor as cursor.
<?php
$base = "https://api.getprice.ai/v1";
$key = getenv("GETPRICE_API_KEY");
$query = http_build_query([
    "limit" => "500",
]);
$ch = curl_init("$base/sku-mappings?$query");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $key",
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($body === false || $status >= 400) {
    throw new RuntimeException(
        "GetPrice returned $status: $body"
    );
}
$data = json_decode(
    $body, true, flags: JSON_THROW_ON_ERROR
);

foreach ($data["data"] as $m) {
    $target = $m["product_id"]
        ?? $m["comparison_set_id"];
    echo $m["sku"], " ", $target, "\n";
}
// More? Send $data["next_cursor"] as cursor.
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;
using Naming = System.Text.Json.JsonNamingPolicy;

var key = Environment.GetEnvironmentVariable(
    "GETPRICE_API_KEY");
var api = new Uri("https://api.getprice.ai/v1/");
var http = new HttpClient { BaseAddress = api };
http.Timeout = TimeSpan.FromSeconds(30);
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", key);
var json = new JsonSerializerOptions
{
    PropertyNamingPolicy = Naming.SnakeCaseLower,
};

var res = await http.GetAsync("sku-mappings?limit=500");
res.EnsureSuccessStatusCode();
var page = await res.Content
    .ReadFromJsonAsync<Page>(json);
foreach (var m in page!.Data)
    Console.WriteLine(
        $"{m.Sku} {m.ProductId ?? m.ComparisonSetId}");
// More? Send page.NextCursor as cursor.

record Page(List<SkuMapping> Data, string? NextCursor);
record SkuMapping(
    string Sku,
    string? ProductId,
    string? ComparisonSetId);
Response200
{
  "data": [
    {
      "sku": "AC-12K-INV",
      "product_id": null,
      "comparison_set_id": "set_Wq3NdT5v",
      "source": "list_sku",
      "created_at": "2026-11-01T16:20:00Z",
      "updated_at": "2026-11-01T16:20:00Z"
    },
    {
      "sku": "DRL-18V-K2",
      "product_id": "prd_Lp4sT1x9",
      "comparison_set_id": null,
      "source": "api",
      "created_at": "2026-11-02T10:05:00Z",
      "updated_at": "2026-11-02T10:05:00Z"
    },
    {
      "sku": "KTL-17-SS",
      "product_id": "prd_Zt41Hq6m",
      "comparison_set_id": null,
      "source": "site_sku",
      "created_at": "2026-10-30T09:12:44Z",
      "updated_at": "2026-10-30T09:12:44Z"
    },
    {
      "sku": "TV-55UHD",
      "product_id": "prd_8fK2mQa1",
      "comparison_set_id": null,
      "source": "site_sku",
      "created_at": "2026-10-30T09:12:44Z",
      "updated_at": "2026-10-30T09:12:44Z"
    }
  ],
  "next_cursor": null
}

Query parameters

  • limit#integer

    Items per page. Default 100. Values above 500 are treated as 500.

    Default
    100
  • cursor#string

    The next_cursor from the previous page. Opaque: pass it back unchanged, together with the same filters, on the same endpoint, as the first request (otherwise 400 cursor_mismatch).

Headers

  • If-None-Match#string

    An ETag from a previous response. If nothing changed you get 304 Not Modified with no body.

Returns

200

A page of SKU mappings.

  • The SKU mappings on this page, ordered by SKU.

  • next_cursor#stringnullable

    Pass as cursor to get the next page. null on the last page.

Errors

  • 400

    The request is malformed: an invalid or unknown query parameter, a bad cursor, more than 100 sku values, or an invalid SKU in the path (empty after trimming or over 100 characters).

  • 401

    No Authorization: Bearer header (unauthenticated), or a key that doesn't work (invalid_key).

  • 403

    The key is valid but lacks the scope this endpoint needs.

  • 429

    This request costs more rate-limit units than you have left.

  • 500

    Something went wrong on our side.

  • 503

    Temporarily unavailable: GetPrice can't guarantee correct match data right now, or the database is saturated.

How errors are shaped

Retrieve a SKU mapping#

Requires catalog:read

Returns what one of your SKUs is linked to. The response's ETag is the link's version, such as "v42". Send it as If-Match to replace or remove the link only if nobody has changed it since.

BASE=https://api.getprice.ai/v1
curl "$BASE/sku-mappings/TV-55UHD" \
  -H "Authorization: Bearer $GETPRICE_API_KEY"
import os

import requests

BASE = "https://api.getprice.ai/v1"
KEY = os.environ["GETPRICE_API_KEY"]

resp = requests.get(
    f"{BASE}/sku-mappings/TV-55UHD",
    headers={"Authorization": f"Bearer {KEY}"},
    timeout=30,
)
resp.raise_for_status()
mapping = resp.json()
print(mapping["sku"], mapping["product_id"])
print("ETag:", resp.headers["ETag"])
interface SkuMapping {
  sku: string;
  product_id: string | null;
}

const BASE = "https://api.getprice.ai/v1";
const KEY = process.env.GETPRICE_API_KEY;
const url = `${BASE}/sku-mappings/TV-55UHD`;
const res = await fetch(url, {
  headers: { Authorization: `Bearer ${KEY}` },
});
if (!res.ok) {
  throw new Error(`GetPrice returned ${res.status}`);
}
const mapping = (await res.json()) as SkuMapping;
console.log(mapping.sku, mapping.product_id);
console.log("ETag:", res.headers.get("etag"));
<?php
$base = "https://api.getprice.ai/v1";
$key = getenv("GETPRICE_API_KEY");
$etag = null;
$ch = curl_init("$base/sku-mappings/TV-55UHD");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $key",
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HEADERFUNCTION =>
        function ($ch, $line) use (&$etag) {
            if (stripos($line, "ETag:") === 0) {
                $etag = trim(substr($line, 5));
            }
            return strlen($line);
        },
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($body === false || $status >= 400) {
    throw new RuntimeException(
        "GetPrice returned $status: $body"
    );
}
$data = json_decode(
    $body, true, flags: JSON_THROW_ON_ERROR
);

echo $data["sku"], " ", $data["product_id"], "\n";
echo "ETag: ", $etag, "\n";
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;
using Naming = System.Text.Json.JsonNamingPolicy;

var key = Environment.GetEnvironmentVariable(
    "GETPRICE_API_KEY");
var api = new Uri("https://api.getprice.ai/v1/");
var http = new HttpClient { BaseAddress = api };
http.Timeout = TimeSpan.FromSeconds(30);
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", key);
var json = new JsonSerializerOptions
{
    PropertyNamingPolicy = Naming.SnakeCaseLower,
};

var res = await http.GetAsync("sku-mappings/TV-55UHD");
res.EnsureSuccessStatusCode();
var mapping = await res.Content
    .ReadFromJsonAsync<SkuMapping>(json);
Console.WriteLine(
    $"{mapping!.Sku} {mapping.ProductId}");
Console.WriteLine($"ETag: {res.Headers.ETag?.Tag}");

record SkuMapping(string Sku, string? ProductId);
Response200
{
  "sku": "TV-55UHD",
  "product_id": "prd_8fK2mQa1",
  "comparison_set_id": null,
  "source": "site_sku",
  "created_at": "2026-10-30T09:12:44Z",
  "updated_at": "2026-10-30T09:12:44Z"
}

Path parameters

  • sku#stringRequired

    Your SKU, percent-encoded. SKUs may contain /, spaces, +, % and non-ASCII characters; encode every reserved character (for example AB/12 X becomes AB%2F12%20X). Surrounding whitespace (space, tab, CR, LF, non-breaking space) is trimmed. A SKU can't contain line breaks or other control characters inside it.

Headers

  • If-None-Match#string

    An ETag from a previous response. If nothing changed you get 304 Not Modified with no body.

Returns

200

The SKU mapping.

Returns the SKU mapping object.

Errors

  • 400

    The request is malformed: an invalid or unknown query parameter, a bad cursor, more than 100 sku values, or an invalid SKU in the path (empty after trimming or over 100 characters).

  • 401

    No Authorization: Bearer header (unauthenticated), or a key that doesn't work (invalid_key).

  • 403

    The key is valid but lacks the scope this endpoint needs.

  • 404

    Not found for your company.

  • 429

    This request costs more rate-limit units than you have left.

  • 500

    Something went wrong on our side.

  • 503

    Temporarily unavailable: GetPrice can't guarantee correct match data right now, or the database is saturated.

How errors are shaped

Create or replace a SKU mapping#

Requires skus:write

Links your SKU to one of your own products, creating or replacing the link. Returns 201 with a Location header for a new link, and 200 when it replaced one.

Sending the same request twice has the same effect as sending it once. Surrounding whitespace in the SKU is trimmed. A product id that isn't one of your own products returns 404 product_not_found.

A SKU that is on one of your website products stays with it: linking it to a product built from your catalogue returns 409 sku_on_website, with the website product's id in product_id, and nothing changes.

The old id of a catalogue product that your website product replaced (see replaced_from on GET /v1/products/{product_id}) links the SKU to the website product; the response's product_id is the website product's id.

To avoid overwriting someone else's link:

  • If-None-Match: * creates only. If the SKU is already linked, you get 412 and nothing changes.
  • If-Match: <ETag> replaces only if the link hasn't changed since you read it. Otherwise you get 412.
BASE=https://api.getprice.ai/v1
curl -X PUT "$BASE/sku-mappings/DRL-18V-K2" \
  -H "Authorization: Bearer $GETPRICE_API_KEY" \
  -H "If-None-Match: *" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "prd_Lp4sT1x9"}'
import os

import requests

BASE = "https://api.getprice.ai/v1"
KEY = os.environ["GETPRICE_API_KEY"]

resp = requests.put(
    f"{BASE}/sku-mappings/DRL-18V-K2",
    json={"product_id": "prd_Lp4sT1x9"},
    headers={
        "Authorization": f"Bearer {KEY}",
        "If-None-Match": "*",
    },
    timeout=30,
)
resp.raise_for_status()
created = resp.status_code == 201
print("created" if created else "replaced")
const BASE = "https://api.getprice.ai/v1";
const KEY = process.env.GETPRICE_API_KEY;
const url = `${BASE}/sku-mappings/DRL-18V-K2`;
const res = await fetch(url, {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${KEY}`,
    "Content-Type": "application/json",
    "If-None-Match": "*",
  },
  body: JSON.stringify({
    product_id: "prd_Lp4sT1x9",
  }),
});
if (!res.ok) {
  throw new Error(`GetPrice returned ${res.status}`);
}
const created = res.status === 201;
console.log(created ? "created" : "replaced");
<?php
$base = "https://api.getprice.ai/v1";
$key = getenv("GETPRICE_API_KEY");
$ch = curl_init("$base/sku-mappings/DRL-18V-K2");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "PUT",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $key",
        "Content-Type: application/json",
        "If-None-Match: *",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "product_id" => "prd_Lp4sT1x9",
    ]),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($body === false || $status >= 400) {
    throw new RuntimeException(
        "GetPrice returned $status: $body"
    );
}

echo $status === 201 ? "created" : "replaced", "\n";
using System.Net.Http.Headers;
using System.Net.Http.Json;

var key = Environment.GetEnvironmentVariable(
    "GETPRICE_API_KEY");
var api = new Uri("https://api.getprice.ai/v1/");
var http = new HttpClient { BaseAddress = api };
http.Timeout = TimeSpan.FromSeconds(30);
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", key);

var req = new HttpRequestMessage(
    HttpMethod.Put, "sku-mappings/DRL-18V-K2")
{
    Content = JsonContent.Create(
        new { product_id = "prd_Lp4sT1x9" }),
};
// Create only: 412 if the SKU is already linked.
req.Headers.IfNoneMatch.Add(EntityTagHeaderValue.Any);
var res = await http.SendAsync(req);
res.EnsureSuccessStatusCode();
var created = (int)res.StatusCode == 201;
Console.WriteLine(created ? "created" : "replaced");
Response200
{
  "sku": "TV-55UHD",
  "product_id": "prd_8fK2mQa1",
  "comparison_set_id": null,
  "source": "site_sku",
  "created_at": "2026-10-30T09:12:44Z",
  "updated_at": "2026-10-30T09:12:44Z"
}

Path parameters

  • sku#stringRequired

    Your SKU, percent-encoded. SKUs may contain /, spaces, +, % and non-ASCII characters; encode every reserved character (for example AB/12 X becomes AB%2F12%20X). Surrounding whitespace (space, tab, CR, LF, non-breaking space) is trimmed. A SKU can't contain line breaks or other control characters inside it.

Headers

  • If-None-Match#string

    * to create only (412 if the SKU is already linked).

    Value
    *
  • If-Match#string

    The ETag from a previous GET /v1/sku-mappings/{sku}; replace only if unchanged.

Body parameters

  • product_id#stringRequired

    One of your own products (from GET /v1/products).

    Example
    prd_8fK2mQa1

Returns

200

An existing link was replaced (or re-sent unchanged).

Returns the SKU mapping object.

201

A new link was created.

Returns the SKU mapping object.

Errors

  • 400

    The request is malformed: an invalid or unknown query parameter, a bad cursor, more than 100 sku values, or an invalid SKU in the path (empty after trimming or over 100 characters).

  • 401

    No Authorization: Bearer header (unauthenticated), or a key that doesn't work (invalid_key).

  • 403

    The key is valid but lacks the scope this endpoint needs.

  • 404

    product_id is not one of your own products (for example a competitor's product, or an unknown id).

  • 409

    The SKU is on one of your website products, and product_id is a product built from your catalogue.

  • 412

    If-Match did not match, or If-None-Match: * was sent and the SKU is already linked.

  • 413

    Request body over 1 MB.

  • 415

    The body is not application/json.

  • 422

    The body is not valid: not JSON, missing product_id, or extra fields.

  • 429

    This request costs more rate-limit units than you have left.

  • 500

    Something went wrong on our side.

  • 503

    Temporarily unavailable: GetPrice can't guarantee correct match data right now, or the database is saturated.

How errors are shaped

Delete a SKU mapping#

Requires skus:write

Deletes the SKU mapping for your SKU and returns 204. Your product and its comparison set stay as they are. Returns 404 if the SKU isn't linked.

BASE=https://api.getprice.ai/v1
curl -X DELETE "$BASE/sku-mappings/DRL-18V-K2" \
  -H "Authorization: Bearer $GETPRICE_API_KEY"
import os

import requests

BASE = "https://api.getprice.ai/v1"
KEY = os.environ["GETPRICE_API_KEY"]

resp = requests.delete(
    f"{BASE}/sku-mappings/DRL-18V-K2",
    headers={"Authorization": f"Bearer {KEY}"},
    timeout=30,
)
resp.raise_for_status()
print("unlinked")
const BASE = "https://api.getprice.ai/v1";
const KEY = process.env.GETPRICE_API_KEY;
const url = `${BASE}/sku-mappings/DRL-18V-K2`;
const res = await fetch(url, {
  method: "DELETE",
  headers: { Authorization: `Bearer ${KEY}` },
});
if (!res.ok) {
  throw new Error(`GetPrice returned ${res.status}`);
}
console.log("unlinked");
<?php
$base = "https://api.getprice.ai/v1";
$key = getenv("GETPRICE_API_KEY");
$ch = curl_init("$base/sku-mappings/DRL-18V-K2");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "DELETE",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $key",
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($body === false || $status >= 400) {
    throw new RuntimeException(
        "GetPrice returned $status: $body"
    );
}

echo "unlinked\n";
using System.Net.Http.Headers;

var key = Environment.GetEnvironmentVariable(
    "GETPRICE_API_KEY");
var api = new Uri("https://api.getprice.ai/v1/");
var http = new HttpClient { BaseAddress = api };
http.Timeout = TimeSpan.FromSeconds(30);
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", key);

var res = await http.DeleteAsync(
    "sku-mappings/DRL-18V-K2");
res.EnsureSuccessStatusCode();
Console.WriteLine("unlinked");
Response204

No response body.

Path parameters

  • sku#stringRequired

    Your SKU, percent-encoded. SKUs may contain /, spaces, +, % and non-ASCII characters; encode every reserved character (for example AB/12 X becomes AB%2F12%20X). Surrounding whitespace (space, tab, CR, LF, non-breaking space) is trimmed. A SKU can't contain line breaks or other control characters inside it.

Headers

  • If-Match#string

    The ETag from a previous GET; delete only if unchanged.

Returns

204

The link was removed.

Errors

  • 400

    The request is malformed: an invalid or unknown query parameter, a bad cursor, more than 100 sku values, or an invalid SKU in the path (empty after trimming or over 100 characters).

  • 401

    No Authorization: Bearer header (unauthenticated), or a key that doesn't work (invalid_key).

  • 403

    The key is valid but lacks the scope this endpoint needs.

  • 404

    The resource does not exist for your company.

  • 412

    If-Match did not match, or If-None-Match: * was sent and the SKU is already linked.

  • 429

    This request costs more rate-limit units than you have left.

  • 500

    Something went wrong on our side.

  • 503

    Temporarily unavailable: GetPrice can't guarantee correct match data right now, or the database is saturated.

How errors are shaped