openapi: 3.1.0
info:
  title: GetPrice API
  version: 1.0.0
  summary: Read competitor prices for your products and link your own SKUs to them.
  description: |
    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.

    - Look up competitor prices for up to 100 SKUs: `GET /v1/comparison-sets?sku=…`.
    - Sync every comparison set into your ERP: `GET /v1/comparison-sets`.
    - Link your SKUs to your products: `GET /v1/products`, then `PUT /v1/sku-mappings/{sku}`.

    New here? Start with the [quickstart](https://www.getprice.ai/developers/quickstart).

    **Conventions**

    - JSON over HTTPS. Property and parameter names are `snake_case`.
    - Times are UTC, for example `2026-11-02T04:12:09Z`.
    - Money is a decimal string with a currency: `{"amount": "8999.00", "currency": "ZAR"}`. Don't parse it as a
      float.
    - Every documented field is always present. `null` means "no value", and lists are `[]`, never `null`.
    - Ids such as `prd_…`, `set_…` and `cmp_…` are opaque. Store them; don't parse them.
    - Ignore fields you don't recognise, and expect new enum values. Within v1 we only add things.
    - Every response has an `X-Request-Id`. Quote it when you contact support.
    - v1 was released on 2026-11-02. Changes are listed in the [changelog](https://www.getprice.ai/developers/changelog).

    **Acceptable use.** API data is for your organisation's internal use. Don't publish or publicly display
    competitor prices, including on in-store digital price tags, without GetPrice's written agreement.

    Support: support@getprice.ai
  contact:
    name: GetPrice support
    email: support@getprice.ai
    url: https://www.getprice.ai
  termsOfService: https://www.getprice.ai/terms
  license:
    name: Proprietary
    identifier: LicenseRef-GetPrice-Proprietary
servers:
  - url: https://api.getprice.ai/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Account
    description: Check which API key you're using and what it can do.
  - name: Comparison sets
    description: |
      A comparison set is one of your products plus the same item at each competitor, with their latest prices.
      Use it for price checks and ERP syncs.
  - name: Products
    description: Your own products, as GetPrice collects them from your online shop.
  - name: Competitors
    description: The competitor websites GetPrice tracks for you.
  - name: SKU mappings
    description: |
      Links from your own SKUs to your products in GetPrice. Create, replace and remove them so you can look up
      prices by the codes your ERP already uses.

paths:
  /me:
    get:
      operationId: getMe
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |
            BASE=https://api.getprice.ai/v1
            curl "$BASE/me" \
              -H "Authorization: Bearer $GETPRICE_API_KEY"
        - lang: python
          label: Python
          source: |
            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")
        - lang: typescript
          label: TypeScript
          source: |
            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`);
        - lang: php
          label: PHP
          source: |
            <?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"],
            );
        - lang: csharp
          label: C#
          source: |
            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);
      tags: [Account]
      summary: Check your API key
      description: |
        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.
      parameters:
        - $ref: '#/components/parameters/IfNoneMatch'
      responses:
        '200':
          description: The calling key.
          headers:
            X-Request-Id: { $ref: '#/components/headers/X-Request-Id' }
            RateLimit-Policy: { $ref: '#/components/headers/RateLimit-Policy' }
            RateLimit: { $ref: '#/components/headers/RateLimit' }
            X-RateLimit-Limit: { $ref: '#/components/headers/X-RateLimit-Limit' }
            X-RateLimit-Remaining: { $ref: '#/components/headers/X-RateLimit-Remaining' }
            X-RateLimit-Reset: { $ref: '#/components/headers/X-RateLimit-Reset' }
            ETag: { $ref: '#/components/headers/ETag' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Me' }
              examples:
                example:
                  summary: A production key
                  value:
                    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
        '304': { $ref: '#/components/responses/NotModified' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '500': { $ref: '#/components/responses/InternalError' }
        '503': { $ref: '#/components/responses/Unavailable' }

  /comparison-sets:
    get:
      operationId: listComparisonSets
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |
            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"
        - lang: python
          label: Python
          source: |
            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"])
        - lang: typescript
          label: TypeScript
          source: |
            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);
              }
            }
        - lang: php
          label: PHP
          source: |
            <?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";
                }
            }
        - lang: csharp
          label: C#
          source: |
            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);
      tags: [Comparison sets]
      summary: List comparison sets
      description: |
        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`.
      security:
        - bearerAuth: [matches:read]
      parameters:
        - $ref: '#/components/parameters/SkuFilter'
        - $ref: '#/components/parameters/ReviewedBy'
        - $ref: '#/components/parameters/IncludeDelisted'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/IfNoneMatch'
      responses:
        '200':
          description: A page of comparison sets.
          headers:
            X-Request-Id: { $ref: '#/components/headers/X-Request-Id' }
            ETag: { $ref: '#/components/headers/ETag' }
            RateLimit-Policy: { $ref: '#/components/headers/RateLimit-Policy' }
            RateLimit: { $ref: '#/components/headers/RateLimit' }
            X-RateLimit-Limit: { $ref: '#/components/headers/X-RateLimit-Limit' }
            X-RateLimit-Remaining: { $ref: '#/components/headers/X-RateLimit-Remaining' }
            X-RateLimit-Reset: { $ref: '#/components/headers/X-RateLimit-Reset' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ComparisonSetList' }
              examples:
                bySku:
                  summary: Look up SKUs (?sku=TV-55UHD&sku=KTL-17-SS&sku=TEA-RB80-C12)
                  value:
                    data:
                      - &tvSet
                        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 }
                allSets:
                  summary: Sync everything (no sku filter)
                  value:
                    data:
                      - *tvSet
                      - id: set_R4m8wQe2
                        name: 18V Cordless Hammer Drill Kit, 2 x 2.0Ah Batteries
                        sku: null
                        own_product:
                          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
                          price: { amount: '2499.00', was: '2799.00', currency: ZAR, deal: null }
                          last_collected_at: '2026-11-02T04:12:31Z'
                          stale: false
                          is_catalogue: false
                        competitors:
                          - competitor: { id: cmp_2HdR6wJ3, name: Ironwood Home, domain: ironwood.example.com }
                            product: { id: prd_Bf5Rk2Ws, name: 18V Cordless Hammer Drill + 2 Batteries, url: 'https://ironwood.example.com/tools/18v-cordless-hammer-drill-2-batteries' }
                            price: { amount: '2399.00', was: null, currency: ZAR, deal: null }
                            last_collected_at: '2026-11-02T03:24:17Z'
                            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_Nc8Jt3Yd, name: 'Cordless Hammer Drill 18V Kit, 2.0Ah x2', url: 'https://marula.example.com/p/cordless-hammer-drill-18v-kit-2-0ah-x2' }
                            price: { amount: '2449.00', was: null, currency: ZAR, deal: null }
                            last_collected_at: '2026-11-02T03:13:02Z'
                            availability: unknown
                            status: active
                            stale: false
                            match: { review: same, reviewed_by: getprice, confidence: 0.92 }
                        integrity: ok
                        updated_at: '2026-11-02T04:14:00Z'
                    next_cursor: null
        '304': { $ref: '#/components/responses/NotModified' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '500': { $ref: '#/components/responses/InternalError' }
        '503': { $ref: '#/components/responses/Unavailable' }

  /comparison-sets/{set_id}:
    get:
      operationId: getComparisonSet
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |
            BASE=https://api.getprice.ai/v1
            curl "$BASE/comparison-sets/set_x7Kp2Lm9" \
              -H "Authorization: Bearer $GETPRICE_API_KEY"
        - lang: python
          label: Python
          source: |
            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"])
        - lang: typescript
          label: TypeScript
          source: |
            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);
            }
        - lang: php
          label: PHP
          source: |
            <?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";
            }
        - lang: csharp
          label: C#
          source: |
            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);
      tags: [Comparison sets]
      summary: Retrieve a comparison set
      description: |
        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.
      security:
        - bearerAuth: [matches:read]
      parameters:
        - name: set_id
          in: path
          required: true
          description: The set id, for example `set_x7Kp2Lm9`.
          schema: { $ref: '#/components/schemas/SetId' }
        - $ref: '#/components/parameters/ReviewedBy'
        - $ref: '#/components/parameters/IncludeDelisted'
        - $ref: '#/components/parameters/IfNoneMatch'
      responses:
        '200':
          description: The comparison set.
          headers:
            X-Request-Id: { $ref: '#/components/headers/X-Request-Id' }
            ETag: { $ref: '#/components/headers/ETag' }
            RateLimit-Policy: { $ref: '#/components/headers/RateLimit-Policy' }
            RateLimit: { $ref: '#/components/headers/RateLimit' }
            X-RateLimit-Limit: { $ref: '#/components/headers/X-RateLimit-Limit' }
            X-RateLimit-Remaining: { $ref: '#/components/headers/X-RateLimit-Remaining' }
            X-RateLimit-Reset: { $ref: '#/components/headers/X-RateLimit-Reset' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ComparisonSet' }
              examples:
                tv: { $ref: '#/components/examples/ComparisonSetTv' }
        '304': { $ref: '#/components/responses/NotModified' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404':
          description: Not found for your company. Code `not_found`.
          headers:
            X-Request-Id: { $ref: '#/components/headers/X-Request-Id' }
          content:
            application/problem+json:
              schema: { $ref: '#/components/schemas/Problem' }
              examples:
                unknownSet:
                  summary: Unknown id
                  value:
                    type: https://api.getprice.ai/errors/not-found
                    title: Not found
                    status: 404
                    detail: "No comparison set with this id."
                    code: not_found
                    request_id: req_7f3c2a91d4e84b0c9a6e15b2c8d40f37
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '500': { $ref: '#/components/responses/InternalError' }
        '503': { $ref: '#/components/responses/Unavailable' }

  /products:
    get:
      operationId: listProducts
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |
            BASE=https://api.getprice.ai/v1
            curl -G "$BASE/products" \
              -H "Authorization: Bearer $GETPRICE_API_KEY" \
              --data-urlencode "q=drill" \
              --data-urlencode "unmapped=true"
        - lang: python
          label: Python
          source: |
            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"])
        - lang: typescript
          label: TypeScript
          source: |
            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);
            }
        - lang: php
          label: PHP
          source: |
            <?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";
            }
        - lang: csharp
          label: C#
          source: |
            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);
      tags: [Products]
      summary: List your products
      description: |
        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.
      security:
        - bearerAuth: [catalog:read]
      parameters:
        - $ref: '#/components/parameters/SkuFilter'
        - name: q
          in: query
          required: false
          description: Case-insensitive substring of the product name.
          schema: { type: string, minLength: 1, maxLength: 200 }
          example: drill
        - name: unmapped
          in: query
          required: false
          description: '`true` returns only products with no SKU linked.'
          schema: { type: boolean, default: false }
        - name: include_delisted
          in: query
          required: false
          description: '`true` also returns products no longer on your site (`status: delisted`).'
          schema: { type: boolean, default: false }
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/IfNoneMatch'
      responses:
        '200':
          description: A page of products.
          headers:
            X-Request-Id: { $ref: '#/components/headers/X-Request-Id' }
            ETag: { $ref: '#/components/headers/ETag' }
            RateLimit-Policy: { $ref: '#/components/headers/RateLimit-Policy' }
            RateLimit: { $ref: '#/components/headers/RateLimit' }
            X-RateLimit-Limit: { $ref: '#/components/headers/X-RateLimit-Limit' }
            X-RateLimit-Remaining: { $ref: '#/components/headers/X-RateLimit-Remaining' }
            X-RateLimit-Reset: { $ref: '#/components/headers/X-RateLimit-Reset' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProductList' }
              examples:
                search:
                  summary: GET /v1/products?q=drill&unmapped=true
                  value:
                    data:
                      - &drillProduct
                        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
        '304': { $ref: '#/components/responses/NotModified' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '500': { $ref: '#/components/responses/InternalError' }
        '503': { $ref: '#/components/responses/Unavailable' }

  /products/{product_id}:
    get:
      operationId: getProduct
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |
            BASE=https://api.getprice.ai/v1
            curl "$BASE/products/prd_8fK2mQa1" \
              -H "Authorization: Bearer $GETPRICE_API_KEY"
        - lang: python
          label: Python
          source: |
            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)
        - lang: typescript
          label: TypeScript
          source: |
            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);
        - lang: php
          label: PHP
          source: |
            <?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";
        - lang: csharp
          label: C#
          source: |
            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);
      tags: [Products]
      summary: Retrieve a product
      description: |
        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.
      security:
        - bearerAuth: [catalog:read]
      parameters:
        - name: product_id
          in: path
          required: true
          description: The product id, for example `prd_8fK2mQa1`.
          schema: { $ref: '#/components/schemas/ProductId' }
        - $ref: '#/components/parameters/IfNoneMatch'
      responses:
        '200':
          description: The product.
          headers:
            X-Request-Id: { $ref: '#/components/headers/X-Request-Id' }
            ETag: { $ref: '#/components/headers/ETag' }
            RateLimit-Policy: { $ref: '#/components/headers/RateLimit-Policy' }
            RateLimit: { $ref: '#/components/headers/RateLimit' }
            X-RateLimit-Limit: { $ref: '#/components/headers/X-RateLimit-Limit' }
            X-RateLimit-Remaining: { $ref: '#/components/headers/X-RateLimit-Remaining' }
            X-RateLimit-Reset: { $ref: '#/components/headers/X-RateLimit-Reset' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Product' }
              examples:
                tv: { $ref: '#/components/examples/ProductTv' }
        '304': { $ref: '#/components/responses/NotModified' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404':
          description: Not found for your company. Code `not_found`.
          headers:
            X-Request-Id: { $ref: '#/components/headers/X-Request-Id' }
          content:
            application/problem+json:
              schema: { $ref: '#/components/schemas/Problem' }
              examples:
                unknownProduct:
                  summary: Unknown id
                  value:
                    type: https://api.getprice.ai/errors/not-found
                    title: Not found
                    status: 404
                    detail: "No product of yours with this id."
                    code: not_found
                    request_id: req_7f3c2a91d4e84b0c9a6e15b2c8d40f37
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '500': { $ref: '#/components/responses/InternalError' }
        '503': { $ref: '#/components/responses/Unavailable' }

  /competitors:
    get:
      operationId: listCompetitors
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |
            BASE=https://api.getprice.ai/v1
            curl "$BASE/competitors" \
              -H "Authorization: Bearer $GETPRICE_API_KEY"
        - lang: python
          label: Python
          source: |
            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"])
        - lang: typescript
          label: TypeScript
          source: |
            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);
            }
        - lang: php
          label: PHP
          source: |
            <?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";
            }
        - lang: csharp
          label: C#
          source: |
            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);
      tags: [Competitors]
      summary: List competitors
      description: |
        Returns the competitor websites GetPrice collects prices from for you.
      security:
        - bearerAuth: [catalog:read]
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/IfNoneMatch'
      responses:
        '200':
          description: A page of competitors.
          headers:
            X-Request-Id: { $ref: '#/components/headers/X-Request-Id' }
            ETag: { $ref: '#/components/headers/ETag' }
            RateLimit-Policy: { $ref: '#/components/headers/RateLimit-Policy' }
            RateLimit: { $ref: '#/components/headers/RateLimit' }
            X-RateLimit-Limit: { $ref: '#/components/headers/X-RateLimit-Limit' }
            X-RateLimit-Remaining: { $ref: '#/components/headers/X-RateLimit-Remaining' }
            X-RateLimit-Reset: { $ref: '#/components/headers/X-RateLimit-Reset' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CompetitorList' }
              examples:
                example:
                  summary: Retail competitors
                  value:
                    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
        '304': { $ref: '#/components/responses/NotModified' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '500': { $ref: '#/components/responses/InternalError' }
        '503': { $ref: '#/components/responses/Unavailable' }

  /sku-mappings:
    get:
      operationId: listSkuMappings
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |
            BASE=https://api.getprice.ai/v1
            curl -G "$BASE/sku-mappings" \
              -H "Authorization: Bearer $GETPRICE_API_KEY" \
              --data-urlencode "limit=500"
        - lang: python
          label: Python
          source: |
            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.
        - lang: typescript
          label: TypeScript
          source: |
            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.
        - lang: php
          label: PHP
          source: |
            <?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.
        - lang: csharp
          label: C#
          source: |
            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);
      tags: [SKU mappings]
      summary: List SKU mappings
      description: |
        Returns every SKU link you have, ordered by SKU.
      security:
        - bearerAuth: [catalog:read]
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/IfNoneMatch'
      responses:
        '200':
          description: A page of SKU mappings.
          headers:
            X-Request-Id: { $ref: '#/components/headers/X-Request-Id' }
            ETag: { $ref: '#/components/headers/ETag' }
            RateLimit-Policy: { $ref: '#/components/headers/RateLimit-Policy' }
            RateLimit: { $ref: '#/components/headers/RateLimit' }
            X-RateLimit-Limit: { $ref: '#/components/headers/X-RateLimit-Limit' }
            X-RateLimit-Remaining: { $ref: '#/components/headers/X-RateLimit-Remaining' }
            X-RateLimit-Reset: { $ref: '#/components/headers/X-RateLimit-Reset' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SkuMappingList' }
              examples:
                example:
                  value:
                    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'
                      - &drillMap
                        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'
                      - &tvMap
                        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
        '304': { $ref: '#/components/responses/NotModified' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '500': { $ref: '#/components/responses/InternalError' }
        '503': { $ref: '#/components/responses/Unavailable' }

  /sku-mappings/{sku}:
    parameters:
      - name: sku
        in: path
        required: true
        description: |
          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.
        schema: { type: string, minLength: 1, maxLength: 100 }
        example: TV-55UHD
    get:
      operationId: getSkuMapping
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |
            BASE=https://api.getprice.ai/v1
            curl "$BASE/sku-mappings/TV-55UHD" \
              -H "Authorization: Bearer $GETPRICE_API_KEY"
        - lang: python
          label: Python
          source: |
            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"])
        - lang: typescript
          label: TypeScript
          source: |
            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"));
        - lang: php
          label: PHP
          source: |
            <?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";
        - lang: csharp
          label: C#
          source: |
            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);
      tags: [SKU mappings]
      summary: Retrieve a SKU mapping
      description: |
        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.
      security:
        - bearerAuth: [catalog:read]
      parameters:
        - $ref: '#/components/parameters/IfNoneMatch'
      responses:
        '200':
          description: The SKU mapping.
          headers:
            X-Request-Id: { $ref: '#/components/headers/X-Request-Id' }
            ETag: { $ref: '#/components/headers/ETagStrong' }
            Cache-Control: { $ref: '#/components/headers/CacheControlNoCache' }
            RateLimit-Policy: { $ref: '#/components/headers/RateLimit-Policy' }
            RateLimit: { $ref: '#/components/headers/RateLimit' }
            X-RateLimit-Limit: { $ref: '#/components/headers/X-RateLimit-Limit' }
            X-RateLimit-Remaining: { $ref: '#/components/headers/X-RateLimit-Remaining' }
            X-RateLimit-Reset: { $ref: '#/components/headers/X-RateLimit-Reset' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SkuMapping' }
              examples:
                tv: { $ref: '#/components/examples/SkuMappingTv' }
        '304': { $ref: '#/components/responses/NotModified' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404':
          description: Not found for your company. Code `not_found`.
          headers:
            X-Request-Id: { $ref: '#/components/headers/X-Request-Id' }
          content:
            application/problem+json:
              schema: { $ref: '#/components/schemas/Problem' }
              examples:
                unlinkedSku:
                  summary: SKU not linked
                  value:
                    type: https://api.getprice.ai/errors/not-found
                    title: Not found
                    status: 404
                    detail: "No mapping for this SKU."
                    code: not_found
                    request_id: req_7f3c2a91d4e84b0c9a6e15b2c8d40f37
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '500': { $ref: '#/components/responses/InternalError' }
        '503': { $ref: '#/components/responses/Unavailable' }
    put:
      operationId: putSkuMapping
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |
            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"}'
        - lang: python
          label: Python
          source: |
            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")
        - lang: typescript
          label: TypeScript
          source: |
            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");
        - lang: php
          label: PHP
          source: |
            <?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";
        - lang: csharp
          label: C#
          source: |
            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");
      tags: [SKU mappings]
      summary: Create or replace a SKU mapping
      description: |
        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.
      security:
        - bearerAuth: [skus:write]
      parameters:
        - name: If-None-Match
          in: header
          required: false
          description: '`*` to create only (412 if the SKU is already linked).'
          schema: { type: string, const: '*' }
        - name: If-Match
          in: header
          required: false
          description: The ETag from a previous `GET /v1/sku-mappings/{sku}`; replace only if unchanged.
          schema: { type: string }
          example: '"v42"'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SkuMappingWrite' }
            examples:
              link:
                value: { product_id: prd_Lp4sT1x9 }
      responses:
        '200':
          description: An existing link was replaced (or re-sent unchanged).
          headers:
            X-Request-Id: { $ref: '#/components/headers/X-Request-Id' }
            ETag: { $ref: '#/components/headers/ETagStrong' }
            Cache-Control: { $ref: '#/components/headers/CacheControlNoCache' }
            RateLimit-Policy: { $ref: '#/components/headers/RateLimit-Policy' }
            RateLimit: { $ref: '#/components/headers/RateLimit' }
            X-RateLimit-Limit: { $ref: '#/components/headers/X-RateLimit-Limit' }
            X-RateLimit-Remaining: { $ref: '#/components/headers/X-RateLimit-Remaining' }
            X-RateLimit-Reset: { $ref: '#/components/headers/X-RateLimit-Reset' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SkuMapping' }
              examples:
                tv: { $ref: '#/components/examples/SkuMappingTv' }
        '201':
          description: A new link was created.
          headers:
            X-Request-Id: { $ref: '#/components/headers/X-Request-Id' }
            ETag: { $ref: '#/components/headers/ETagStrong' }
            Cache-Control: { $ref: '#/components/headers/CacheControlNoCache' }
            Location:
              description: URL of the new mapping.
              schema: { type: string }
              example: /v1/sku-mappings/DRL-18V-K2
            RateLimit-Policy: { $ref: '#/components/headers/RateLimit-Policy' }
            RateLimit: { $ref: '#/components/headers/RateLimit' }
            X-RateLimit-Limit: { $ref: '#/components/headers/X-RateLimit-Limit' }
            X-RateLimit-Remaining: { $ref: '#/components/headers/X-RateLimit-Remaining' }
            X-RateLimit-Reset: { $ref: '#/components/headers/X-RateLimit-Reset' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SkuMapping' }
              examples:
                drill: { $ref: '#/components/examples/SkuMappingDrill' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404':
          description: |
            `product_id` is not one of your own products (for example a competitor's product, or an unknown id).
            Code: `product_not_found`.
          headers:
            X-Request-Id: { $ref: '#/components/headers/X-Request-Id' }
          content:
            application/problem+json:
              schema: { $ref: '#/components/schemas/Problem' }
              examples:
                notOwnProduct:
                  value:
                    type: https://api.getprice.ai/errors/product-not-found
                    title: Not found
                    status: 404
                    detail: No product prd_Q2vN9cD4 among this company's own products.
                    code: product_not_found
                    request_id: req_7f3c2a91d4e84b0c9a6e15b2c8d40f37
        '409':
          description: |
            The SKU is on one of your website products, and `product_id` is a product built from your catalogue. The
            website product keeps the SKU; its id is in the body's `product_id`. Nothing changes. Code:
            `sku_on_website`. Checked before `If-None-Match` and `If-Match`, so it is never hidden by a 412.
            Code `conflict` means the link clashed with another change: read it again, then decide.
          headers:
            X-Request-Id: { $ref: '#/components/headers/X-Request-Id' }
          content:
            application/problem+json:
              schema:
                allOf:
                  - { $ref: '#/components/schemas/Problem' }
                  - type: object
                    properties:
                      product_id:
                        type: string
                        description: With `sku_on_website`, the website product that has this SKU.
                        examples: [prd_8fK2mQxz]
              examples:
                skuOnWebsite:
                  value:
                    type: https://api.getprice.ai/errors/sku-on-website
                    title: SKU belongs to a website product
                    status: 409
                    detail: This SKU is on one of your website products. A catalogue product can't take it.
                    code: sku_on_website
                    request_id: req_7f3c2a91d4e84b0c9a6e15b2c8d40f37
                    product_id: prd_8fK2mQxz
        '412': { $ref: '#/components/responses/PreconditionFailed' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '422': { $ref: '#/components/responses/UnprocessableContent' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '500': { $ref: '#/components/responses/InternalError' }
        '503': { $ref: '#/components/responses/Unavailable' }
    delete:
      operationId: deleteSkuMapping
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |
            BASE=https://api.getprice.ai/v1
            curl -X DELETE "$BASE/sku-mappings/DRL-18V-K2" \
              -H "Authorization: Bearer $GETPRICE_API_KEY"
        - lang: python
          label: Python
          source: |
            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")
        - lang: typescript
          label: TypeScript
          source: |
            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");
        - lang: php
          label: PHP
          source: |
            <?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";
        - lang: csharp
          label: C#
          source: |
            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");
      tags: [SKU mappings]
      summary: Delete a SKU mapping
      description: |
        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.
      security:
        - bearerAuth: [skus:write]
      parameters:
        - name: If-Match
          in: header
          required: false
          description: The ETag from a previous `GET`; delete only if unchanged.
          schema: { type: string }
      responses:
        '204':
          description: The link was removed.
          headers:
            X-Request-Id: { $ref: '#/components/headers/X-Request-Id' }
            RateLimit-Policy: { $ref: '#/components/headers/RateLimit-Policy' }
            RateLimit: { $ref: '#/components/headers/RateLimit' }
            X-RateLimit-Limit: { $ref: '#/components/headers/X-RateLimit-Limit' }
            X-RateLimit-Remaining: { $ref: '#/components/headers/X-RateLimit-Remaining' }
            X-RateLimit-Reset: { $ref: '#/components/headers/X-RateLimit-Reset' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '412': { $ref: '#/components/responses/PreconditionFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '500': { $ref: '#/components/responses/InternalError' }
        '503': { $ref: '#/components/responses/Unavailable' }

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: GetPrice API key (gp_live_…)
      description: |
        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`.

        | Scope | Grants |
        |---|---|
        | `catalog:read` | your products, competitors, SKU links |
        | `matches:read` | comparison sets (competitor matches and prices) |
        | `skus:write` | create, replace and remove SKU links |

  parameters:
    Limit:
      name: limit
      in: query
      required: false
      description: Items per page. Default 100. Values above 500 are treated as 500.
      schema: { type: integer, minimum: 1, default: 100 }
    Cursor:
      name: cursor
      in: query
      required: false
      description: |
        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`).
      schema: { type: string }
    SkuFilter:
      name: sku
      in: query
      required: false
      description: |
        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.
      style: form
      explode: true
      schema:
        type: array
        maxItems: 100
        items: { type: string, minLength: 1, maxLength: 100 }
      example: [TV-55UHD, DRL-18V-K2]
    ReviewedBy:
      name: reviewed_by
      in: query
      required: false
      description: '`customer` returns only competitors your own users have confirmed. Omit for every competitor in the set.'
      schema: { type: string, enum: [customer] }
    IncludeDelisted:
      name: include_delisted
      in: query
      required: false
      description: '`true` also returns competitor products that are no longer listed (`status: delisted`).'
      schema: { type: boolean, default: false }
    IfNoneMatch:
      name: If-None-Match
      in: header
      required: false
      description: An ETag from a previous response. If nothing changed you get `304 Not Modified` with no body.
      schema: { type: string }
      example: W/"9f3c1e"

  headers:
    X-Request-Id:
      description: Unique id for this request (`req_…`). Quote it when contacting support.
      schema: { type: string }
      example: req_7f3c2a91d4e84b0c9a6e15b2c8d40f37
    ETag:
      description: |
        Weak validator for this representation. Send it back in `If-None-Match` to get a 304. These responses
        also carry `Cache-Control: private, max-age=60`.
      schema: { type: string }
      example: W/"9f3c1e"
    RateLimit-Policy:
      description: |
        Your limits (IETF draft-ietf-httpapi-ratelimit-headers). `q` = quota, `w` = window in seconds.
      schema: { type: string }
      example: '"sustained";q=120;w=60'
    RateLimit:
      description: What is left right now. `r` = units remaining, `t` = seconds until the budget is full again.
      schema: { type: string }
      example: '"sustained";r=117;t=12'
    X-RateLimit-Limit:
      description: Rate-limit units per minute. Most requests cost 1 unit.
      schema: { type: integer }
      example: 120
    X-RateLimit-Remaining:
      description: Units left in the current minute. Drops by each request's cost.
      schema: { type: integer }
      example: 117
    X-RateLimit-Reset:
      description: Seconds until the per-minute allowance resets (a duration, not a timestamp).
      schema: { type: integer }
      example: 12
    ETagStrong:
      description: |
        Strong validator: the SKU link's version, such as `"v42"`. Send it as `If-Match` to replace or remove the
        link only if it hasn't changed, or as `If-None-Match` to get a 304. Treat it as opaque.
      schema: { type: string }
      example: '"v42"'
    CacheControlNoCache:
      description: '`private, no-cache`: a SKU link you just changed is never served from a cache.'
      schema: { type: string }
      example: private, no-cache
    Retry-After:
      description: Seconds to wait before retrying.
      schema: { type: integer }
      example: 21
    WWW-Authenticate:
      description: Bearer challenge (RFC 6750).
      schema: { type: string }
      example: Bearer realm="api.getprice.ai", error="invalid_token"

  responses:
    NotModified:
      description: "Not modified: your cached copy (matching `If-None-Match`) is current. No body."
      headers:
        X-Request-Id: { $ref: '#/components/headers/X-Request-Id' }
        ETag: { $ref: '#/components/headers/ETag' }
    BadRequest:
      description: |
        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). Codes:
        `validation_failed` (a value is invalid), `unknown_parameter` (a parameter this endpoint doesn't take),
        `invalid_parameter` (a query or path value contains a control character), `cursor_mismatch`
        (filters or endpoint changed while paging) and `invalid_cursor` (the cursor is malformed, altered or expired; start
        again without one).
      headers:
        X-Request-Id: { $ref: '#/components/headers/X-Request-Id' }
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
          examples:
            unknownParameter:
              value:
                type: https://api.getprice.ai/errors/unknown-parameter
                title: Unknown query parameter
                status: 400
                detail: "Unknown query parameter(s): update_since."
                code: unknown_parameter
                request_id: req_7f3c2a91d4e84b0c9a6e15b2c8d40f37
                errors:
                  - { parameter: update_since, detail: Unknown parameter. }
            tooManySkus:
              value:
                type: https://api.getprice.ai/errors/validation-failed
                title: Validation failed
                status: 400
                detail: At most 100 sku parameters per request.
                code: validation_failed
                request_id: req_7f3c2a91d4e84b0c9a6e15b2c8d40f37
                errors:
                  - { parameter: sku, detail: At most 100 values. }
            controlCharacter:
              value:
                type: https://api.getprice.ai/errors/invalid-parameter
                title: Invalid parameter
                status: 400
                detail: sku must not contain control characters.
                code: invalid_parameter
                request_id: req_7f3c2a91d4e84b0c9a6e15b2c8d40f37
                errors:
                  - { parameter: sku, detail: Contains a control character. }
            cursorMismatch:
              value:
                type: https://api.getprice.ai/errors/cursor-mismatch
                title: Cursor does not match filters
                status: 400
                detail: Send the same filters as the request that returned this cursor, or start without a cursor.
                code: cursor_mismatch
                request_id: req_7f3c2a91d4e84b0c9a6e15b2c8d40f37
            invalidCursor:
              value:
                type: https://api.getprice.ai/errors/invalid-cursor
                title: Invalid cursor
                status: 400
                detail: The cursor is malformed, altered or expired.
                code: invalid_cursor
                request_id: req_7f3c2a91d4e84b0c9a6e15b2c8d40f37
    Unauthorized:
      description: |
        No `Authorization: Bearer` header (`unauthenticated`), or a key that doesn't work (`invalid_key`). For
        `invalid_key`, `detail` is "The API key is malformed." when the key fails its format or checksum check, and
        "The API key is not valid." for an unknown, revoked or expired key, or a key whose company is closed;
        those four cases are deliberately indistinguishable. Branch on `code`, not on `detail`.
      headers:
        X-Request-Id: { $ref: '#/components/headers/X-Request-Id' }
        WWW-Authenticate: { $ref: '#/components/headers/WWW-Authenticate' }
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
          examples:
            missing:
              summary: No Authorization header
              value:
                type: https://api.getprice.ai/errors/unauthenticated
                title: Authentication required
                status: 401
                detail: "Send Authorization: Bearer <API key>."
                code: unauthenticated
                request_id: req_7f3c2a91d4e84b0c9a6e15b2c8d40f37
            malformedKey:
              summary: Wrong format or checksum (a typo or copy-paste damage)
              value:
                type: https://api.getprice.ai/errors/invalid-key
                title: Invalid API key
                status: 401
                detail: The API key is malformed.
                code: invalid_key
                request_id: req_7f3c2a91d4e84b0c9a6e15b2c8d40f37
            invalidKey:
              summary: Unknown, revoked or expired
              value:
                type: https://api.getprice.ai/errors/invalid-key
                title: Invalid API key
                status: 401
                detail: The API key is not valid.
                code: invalid_key
                request_id: req_7f3c2a91d4e84b0c9a6e15b2c8d40f37
    Forbidden:
      description: |
        The key is valid but lacks the scope this endpoint needs. Code: `insufficient_scope`. The
        `WWW-Authenticate` header names the missing scope.
      headers:
        X-Request-Id: { $ref: '#/components/headers/X-Request-Id' }
        WWW-Authenticate:
          description: The RFC 6750 challenge naming the missing scope.
          schema: { type: string }
          example: Bearer realm="api.getprice.ai", error="insufficient_scope", scope="skus:write"
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
          examples:
            scope:
              value:
                type: https://api.getprice.ai/errors/insufficient-scope
                title: Insufficient scope
                status: 403
                detail: This API key lacks the 'skus:write' scope.
                code: insufficient_scope
                request_id: req_7f3c2a91d4e84b0c9a6e15b2c8d40f37
    NotFound:
      description: |
        The resource does not exist **for your company**. Ids belonging to other companies also return 404.
        Code: `not_found`.
      headers:
        X-Request-Id: { $ref: '#/components/headers/X-Request-Id' }
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
          examples:
            notFound:
              value:
                type: https://api.getprice.ai/errors/not-found
                title: Not found
                status: 404
                detail: No mapping for this SKU.
                code: not_found
                request_id: req_7f3c2a91d4e84b0c9a6e15b2c8d40f37
    PreconditionFailed:
      description: '`If-Match` did not match, or `If-None-Match: *` was sent and the SKU is already linked. Code: `precondition_failed`.'
      headers:
        X-Request-Id: { $ref: '#/components/headers/X-Request-Id' }
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
          examples:
            alreadyLinked:
              value:
                type: https://api.getprice.ai/errors/precondition-failed
                title: Precondition failed
                status: 412
                detail: The SKU mapping exists or changed since you read it; fetch it again before writing.
                code: precondition_failed
                request_id: req_7f3c2a91d4e84b0c9a6e15b2c8d40f37
    PayloadTooLarge:
      description: |
        Request body over 1 MB. Code: `payload_too_large`. Refused up front from `Content-Length`; a chunked or
        mis-declared body that grows past 1 MB while streaming gets the same code with the detail
        "The request body is over 1 MB.".
      headers:
        X-Request-Id: { $ref: '#/components/headers/X-Request-Id' }
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
          examples:
            tooLarge:
              value:
                type: https://api.getprice.ai/errors/payload-too-large
                title: Payload too large
                status: 413
                detail: Payload too large
                code: payload_too_large
                request_id: req_7f3c2a91d4e84b0c9a6e15b2c8d40f37
    UnsupportedMediaType:
      description: 'The body is not `application/json`. Code: `unsupported_media_type`.'
      headers:
        X-Request-Id: { $ref: '#/components/headers/X-Request-Id' }
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
          examples:
            notJson:
              value:
                type: https://api.getprice.ai/errors/unsupported-media-type
                title: Unsupported media type
                status: 415
                detail: Unsupported media type
                code: unsupported_media_type
                request_id: req_7f3c2a91d4e84b0c9a6e15b2c8d40f37
    UnprocessableContent:
      description: |
        The body is not valid: not JSON, missing `product_id`, or extra fields. Code: `validation_failed`, with
        `errors[].pointer` naming the field.
      headers:
        X-Request-Id: { $ref: '#/components/headers/X-Request-Id' }
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
          examples:
            missingField:
              value:
                type: https://api.getprice.ai/errors/validation-failed
                title: Validation failed
                status: 422
                detail: The request did not pass validation; see errors.
                code: validation_failed
                request_id: req_7f3c2a91d4e84b0c9a6e15b2c8d40f37
                errors:
                  - { pointer: /product_id, detail: Field required }
    TooManyRequests:
      description: |
        This request costs more rate-limit units than you have left. The refused request costs nothing. Wait
        `Retry-After` seconds, until enough units are back for it, then retry. Code: `rate_limited`.
      headers:
        X-Request-Id: { $ref: '#/components/headers/X-Request-Id' }
        Retry-After: { $ref: '#/components/headers/Retry-After' }
        RateLimit-Policy: { $ref: '#/components/headers/RateLimit-Policy' }
        RateLimit: { $ref: '#/components/headers/RateLimit' }
        X-RateLimit-Limit: { $ref: '#/components/headers/X-RateLimit-Limit' }
        X-RateLimit-Remaining: { $ref: '#/components/headers/X-RateLimit-Remaining' }
        X-RateLimit-Reset: { $ref: '#/components/headers/X-RateLimit-Reset' }
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
          examples:
            rateLimited:
              value:
                type: https://api.getprice.ai/errors/rate-limited
                title: Rate limit exceeded
                status: 429
                detail: Sustained limit of 120 requests per minute reached for this API key.
                code: rate_limited
                request_id: req_7f3c2a91d4e84b0c9a6e15b2c8d40f37
                limit: sustained
                retry_after: 21
    InternalError:
      description: |
        Something went wrong on our side. **Not retryable**: retrying the same request is unlikely to help. Log the
        `request_id` and contact support if it persists. Code: `internal_error`.
      headers:
        X-Request-Id: { $ref: '#/components/headers/X-Request-Id' }
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
          examples:
            internal:
              value:
                type: https://api.getprice.ai/errors/internal-error
                title: Internal server error
                status: 500
                detail: Internal server error
                code: internal_error
                request_id: req_7f3c2a91d4e84b0c9a6e15b2c8d40f37
    Unavailable:
      description: |
        Temporarily unavailable: GetPrice can't guarantee correct match data right now, or the database is
        saturated. **Retryable**: wait `Retry-After` seconds, then retry. Code: `unavailable`.
      headers:
        X-Request-Id: { $ref: '#/components/headers/X-Request-Id' }
        Retry-After: { $ref: '#/components/headers/Retry-After' }
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
          examples:
            busy:
              value:
                type: https://api.getprice.ai/errors/unavailable
                title: Service unavailable
                status: 503
                detail: The service is busy. Retry shortly.
                code: unavailable
                request_id: req_7f3c2a91d4e84b0c9a6e15b2c8d40f37

  schemas:
    ProductId:
      type: string
      pattern: '^prd_[A-Za-z0-9]+$'
      maxLength: 32
      description: Opaque product id. Stable across URL changes and re-collection.
      examples: [prd_8fK2mQa1]
    SetId:
      type: string
      pattern: '^set_[A-Za-z0-9]+$'
      maxLength: 32
      description: Opaque comparison set id.
      examples: [set_x7Kp2Lm9]
    CompetitorId:
      type: string
      pattern: '^cmp_[A-Za-z0-9]+$'
      maxLength: 32
      description: Opaque competitor (website) id.
      examples: [cmp_3LqV8nP2]
    Money:
      type: string
      pattern: '^-?[0-9]+\.[0-9]{2}$'
      description: Decimal amount with exactly two decimals, as a string. Do not parse as a float.
      examples: ['8999.00']
    Timestamp:
      type: string
      format: date-time
      description: RFC 3339, UTC, `Z` suffix.
      examples: ['2026-11-02T04:12:09Z']

    Price:
      type: object
      description: A price as read from a website. When it was read is the sibling `last_collected_at`.
      required: [amount, was, currency, deal]
      properties:
        amount:
          $ref: '#/components/schemas/Money'
          description: |
            The price a shopper pays now. During a promotion, this is the discounted price. "Cheapest" and
            "position" in GetPrice always use `amount`.
        was:
          description: |
            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).
          oneOf:
            - $ref: '#/components/schemas/Money'
            - type: 'null'
        currency:
          type: string
          pattern: '^[A-Z]{3}$'
          description: ISO 4217 code. Always present.
          examples: [ZAR]
        deal:
          description: |
            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.
          oneOf:
            - $ref: '#/components/schemas/Deal'
            - type: 'null'

    Deal:
      type: object
      description: |
        A deal shown next to a price, read from the same price reading as `amount`. Its money is in the `currency`
        of the price it belongs to.
      required: [text, type, min_qty, unit_price, condition]
      properties:
        text:
          type: string
          description: The deal exactly as the retailer's website shows it. Always present.
          examples: ['BUY 2 OR MORE For R 95.00']
        type:
          description: |
            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.
          oneOf:
            - type: string
              x-extensible-enum: [multi_buy_total, tiered_unit, buy_x_pay_y, buy_x_save_pct, buy_x_save_amount,
                                  member_price, unparsed]
            - type: 'null'
        min_qty:
          description: The number of items to buy to get the deal. `null` when the deal names no quantity.
          oneOf:
            - { type: integer, minimum: 1 }
            - type: 'null'
        unit_price:
          description: |
            The effective price of one item when you buy `min_qty` under the deal. `null` for an `unparsed` deal.
          oneOf:
            - $ref: '#/components/schemas/Money'
            - type: 'null'
        condition:
          description: |
            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.
          oneOf:
            - { type: string, x-extensible-enum: [none, loyalty, online_only] }
            - type: 'null'

    CompetitorRef:
      type: object
      required: [id, name, domain]
      properties:
        id: { $ref: '#/components/schemas/CompetitorId' }
        name: { type: string, description: The competitor's name as shown in the dashboard., examples: [Kestrel Electronics] }
        domain: { type: string, description: The competitor's website host name., examples: [kestrel.example.com] }

    Competitor:
      type: object
      required: [id, name, domain, url]
      properties:
        id: { $ref: '#/components/schemas/CompetitorId' }
        name: { type: string, description: The competitor's name as shown in the dashboard., examples: [Kestrel Electronics] }
        domain: { type: string, description: The competitor's website host name., examples: [kestrel.example.com] }
        url: { type: string, format: uri, description: The competitor's website., examples: ['https://kestrel.example.com'] }

    ProductRef:
      type: object
      description: A competitor's listing of the item, as collected from their site.
      required: [id, name, url]
      properties:
        id: { $ref: '#/components/schemas/ProductId' }
        name: { type: string, description: The product name as the competitor's page shows it. }
        url: { type: string, format: uri, description: The competitor's product page. }

    OwnProductInSet:
      type: object
      required: [id, name, url, price, last_collected_at, stale, is_catalogue]
      properties:
        id: { $ref: '#/components/schemas/ProductId' }
        name: { type: string, description: The product name as your own shop shows it. }
        url:
          type: string
          format: uri
          description: |
            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:
          description: Your current price, or `null` if none has been collected.
          oneOf:
            - $ref: '#/components/schemas/Price'
            - type: 'null'
        last_collected_at:
          description: |
            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`.
          oneOf:
            - $ref: '#/components/schemas/Timestamp'
            - type: 'null'
        stale:
          type: boolean
          description: |
            `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:
          type: boolean
          description: |
            `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](/developers/core-concepts#catalogue-products).

    Match:
      type: object
      description: How this competitor product came to be in the set.
      required: [review, reviewed_by, confidence]
      properties:
        review:
          type: string
          x-extensible-enum: [same, with_differences, unreviewed]
          description: |
            `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.
        reviewed_by:
          description: |
            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.
          oneOf:
            - { type: string, x-extensible-enum: [customer, getprice] }
            - type: 'null'
        confidence:
          description: The matcher's confidence from 0 to 1 when a machine match backs this entry, otherwise `null`.
          oneOf:
            - { type: number, minimum: 0, maximum: 1 }
            - type: 'null'

    CompetitorOffer:
      type: object
      required: [competitor, product, price, last_collected_at, availability, status, stale, match]
      properties:
        competitor: { $ref: '#/components/schemas/CompetitorRef' }
        product: { $ref: '#/components/schemas/ProductRef' }
        price:
          description: The competitor's current price, or `null` if no valid price is available.
          oneOf:
            - $ref: '#/components/schemas/Price'
            - type: 'null'
        last_collected_at:
          description: |
            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`.
          oneOf:
            - $ref: '#/components/schemas/Timestamp'
            - type: 'null'
        availability:
          type: string
          x-extensible-enum: [unknown, in_stock, out_of_stock]
          description: |
            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.
        status:
          type: string
          x-extensible-enum: [active, delisted]
          description: |
            `active` while the product is listed on the competitor's site. `delisted` products are only returned
            with `include_delisted=true`.
        stale:
          type: boolean
          description: |
            `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: { $ref: '#/components/schemas/Match' }

    ComparisonSet:
      type: object
      required: [id, name, sku, own_product, competitors, integrity, updated_at]
      properties:
        id: { $ref: '#/components/schemas/SetId' }
        name: { type: string, description: The set's name in the dashboard (normally your product's name). }
        sku:
          description: Your SKU for this set, or `null` if none is linked.
          oneOf:
            - type: string
            - type: 'null'
        own_product:
          description: Your product in this set, or `null` if the set has no product of yours.
          oneOf:
            - $ref: '#/components/schemas/OwnProductInSet'
            - type: 'null'
        competitors:
          type: array
          description: Every competitor in the set, as the dashboard shows it. `[]` when there are none.
          items: { $ref: '#/components/schemas/CompetitorOffer' }
        integrity:
          type: string
          x-extensible-enum: [ok, retailer_conflict]
          description: |
            `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.
        updated_at:
          $ref: '#/components/schemas/Timestamp'
          description: When the set's contents last changed (not on every price read).

    ComparisonSetList:
      type: object
      required: [data, next_cursor]
      properties:
        data:
          type: array
          description: The comparison sets on this page, in a stable order.
          items: { $ref: '#/components/schemas/ComparisonSet' }
        next_cursor: { $ref: '#/components/schemas/NextCursor' }
        skus:
          type: array
          description: |
            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.
          items: { $ref: '#/components/schemas/SkuStatus' }

    SkuStatus:
      type: object
      required: [sku, status, set_id, product_id]
      properties:
        sku: { type: string, description: The SKU as you sent it (trimmed)., examples: [TV-55UHD] }
        status:
          type: string
          x-extensible-enum: [found, no_comparison_set, unknown_sku]
          description: |
            `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.
        set_id:
          description: The comparison set in `data` when `status` is `found`, otherwise `null`.
          oneOf:
            - $ref: '#/components/schemas/SetId'
            - type: 'null'
        product_id:
          description: The product the SKU is linked to, or `null` for `unknown_sku`.
          oneOf:
            - $ref: '#/components/schemas/ProductId'
            - type: 'null'

    Product:
      type: object
      required: [id, name, url, skus, comparison_set_id, price, last_collected_at, status, is_catalogue,
                 replaced_from]
      properties:
        id: { $ref: '#/components/schemas/ProductId' }
        name: { type: string, description: The product name as your own shop shows it. }
        url:
          type: string
          format: uri
          description: |
            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:
          type: array
          description: Every SKU you have linked to this product. `[]` when none.
          items: { type: string }
        comparison_set_id:
          description: The comparison set this product sits in, or `null` if it is not in one yet.
          oneOf:
            - $ref: '#/components/schemas/SetId'
            - type: 'null'
        price:
          description: Your current price, or `null` if none has been collected.
          oneOf:
            - $ref: '#/components/schemas/Price'
            - type: 'null'
        last_collected_at:
          description: The last time GetPrice successfully read this product's price; `null` when `price` is `null`.
          oneOf:
            - $ref: '#/components/schemas/Timestamp'
            - type: 'null'
        status:
          type: string
          x-extensible-enum: [active, delisted]
          description: '`active`, or `delisted` when the product is no longer on your site (only with `include_delisted=true`). Open set.'
        is_catalogue:
          type: boolean
          description: |
            `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](/developers/core-concepts#catalogue-products).
        replaced_from:
          description: |
            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](/developers/core-concepts#catalogue-products).
          oneOf:
            - $ref: '#/components/schemas/ProductId'
            - type: 'null'

    ProductList:
      type: object
      required: [data, next_cursor]
      properties:
        data:
          type: array
          description: Your products on this page, in a stable order.
          items: { $ref: '#/components/schemas/Product' }
        next_cursor: { $ref: '#/components/schemas/NextCursor' }

    CompetitorList:
      type: object
      required: [data, next_cursor]
      properties:
        data:
          type: array
          description: The competitors on this page, in a stable order.
          items: { $ref: '#/components/schemas/Competitor' }
        next_cursor: { $ref: '#/components/schemas/NextCursor' }

    SkuMapping:
      type: object
      description: |
        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.
      required: [sku, product_id, comparison_set_id, source, created_at, updated_at]
      properties:
        sku: { type: string, description: Your SKU as stored (trimmed)., examples: [TV-55UHD] }
        product_id:
          description: The linked product, or `null` when the SKU is linked to a comparison set instead.
          oneOf:
            - $ref: '#/components/schemas/ProductId'
            - type: 'null'
        comparison_set_id:
          description: |
            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.
          oneOf:
            - $ref: '#/components/schemas/SetId'
            - type: 'null'
        source:
          type: string
          x-extensible-enum: [api, list_sku, site_sku, import, settings_upload]
          description: |
            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.
        created_at: { $ref: '#/components/schemas/Timestamp' }
        updated_at: { $ref: '#/components/schemas/Timestamp' }

    SkuMappingWrite:
      type: object
      required: [product_id]
      additionalProperties: false
      properties:
        product_id:
          $ref: '#/components/schemas/ProductId'
          description: One of your own products (from `GET /v1/products`).

    SkuMappingList:
      type: object
      required: [data, next_cursor]
      properties:
        data:
          type: array
          description: The SKU mappings on this page, ordered by SKU.
          items: { $ref: '#/components/schemas/SkuMapping' }
        next_cursor: { $ref: '#/components/schemas/NextCursor' }

    NextCursor:
      description: Pass as `cursor` to get the next page. `null` on the last page.
      oneOf:
        - type: string
        - type: 'null'

    Me:
      type: object
      required: [key, company, scopes, limits]
      properties:
        key:
          type: object
          description: The key you're calling with. Never includes the secret.
          required: [name, prefix, environment]
          properties:
            name: { type: string, description: The key's name as shown in Settings → API & Integrations. }
            prefix:
              type: string
              description: The public part of the key. Safe to quote to support; identifies the key in logs.
            environment:
              type: string
              x-extensible-enum: [live, test]
              description: '`live` for every key today; there is no test environment yet. `test` is reserved. Open set.'
        company:
          type: object
          description: The organisation this key belongs to. Every request is scoped to it.
          required: [name]
          properties:
            name: { type: string, description: Your organisation's name in GetPrice. }
        scopes:
          type: array
          description: What this key may do. A key created in Settings has all three.
          items:
            type: string
            x-extensible-enum: [catalog:read, matches:read, skus:write]
        limits:
          type: object
          description: This key's rate limit; see the `RateLimit` headers on every response.
          required: [per_minute, window_seconds]
          properties:
            per_minute: { type: integer, description: 'Rate-limit units per window. Most requests cost 1 unit.' }
            window_seconds: { type: integer, description: Length of the rate-limit window in seconds. }

    Problem:
      type: object
      description: RFC 9457 problem details. Branch on `code`, not on `title` or `detail`.
      required: [type, title, status, detail, code, request_id]
      properties:
        type:
          type: string
          format: uri
          description: |
            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: { type: string, description: A short human-readable name for the error type. }
        status: { type: integer, description: The HTTP status code (also in the body). }
        detail: { type: string, description: Human-readable explanation for this occurrence. }
        code:
          type: string
          description: |
            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.
          x-extensible-enum:
            - unauthenticated
            - invalid_key
            - key_revoked
            - insufficient_scope
            - plan_required
            - not_found
            - product_not_found
            - validation_failed
            - unknown_parameter
            - invalid_parameter
            - cursor_mismatch
            - invalid_cursor
            - precondition_failed
            - payload_too_large
            - unsupported_media_type
            - method_not_allowed
            - conflict
            - cursor_expired
            - precondition_required
            - idempotency_key_reused
            - rate_limited
            - concurrency_limited
            - quota_exceeded
            - internal_error
            - unavailable
            - sku_on_website
        request_id: { type: string, description: The same value as the `X-Request-Id` header. Quote it to support., examples: [req_7f3c2a91d4e84b0c9a6e15b2c8d40f37] }
        errors:
          type: array
          description: Field-level details for validation errors.
          items:
            type: object
            required: [detail]
            properties:
              pointer: { type: string, description: 'JSON Pointer into the request body, for example `/product_id`.' }
              parameter: { type: string, description: Name of the offending query parameter. }
              detail: { type: string, description: What is wrong with this field or parameter. }
        limit:
          type: string
          description: On 429, which limit was hit (for example `sustained`).
        retry_after:
          type: integer
          description: On 429, seconds to wait (same as the `Retry-After` header).

  examples:
    ComparisonSetTv:
      summary: 55-inch 4K UHD Smart TV with four competitors
      value: *tvSet
    ProductTv:
      summary: 55-inch 4K UHD Smart TV (own product)
      value:
        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
    SkuMappingTv:
      summary: TV-55UHD → 55-inch 4K UHD Smart TV (read from your website)
      value: *tvMap
    SkuMappingDrill:
      summary: DRL-18V-K2 → the drill, just created through the API
      value: *drillMap
