Catalog reads

Products and matched offers

Retrieve your channel catalog and its currently selected competitor offers, including full available catalog records and current prices.

Set up access

Choose the app capabilities for reading channel products and competitor prices when issuing your API key. Their technical scopes are products:read and competitor_prices:read. Product reads require the first scope; include=offers and every offer route require both.

Existing keys do not gain these scopes automatically. Create a replacement key with a unique name and the required capabilities, switch your client, verify GET /v1/me and GET /v1/capabilities, then revoke the old key. Integration-bound keys remain limited to their connected channels. Scope and channel access are checked on every request, including cached and conditional reads.

Read products and offers

All six endpoints are listed in the API reference. Detail and SKU lookup return {"data": Product}; offer detail returns {"data": Offer}. Product list items use the same Product schema.

Authenticated requests
curl --get 'https://api.pricemind.io/v1/channels/202/products' \
  --header "X-API-Key: $PRICEMIND_API_KEY" \
  --data-urlencode 'limit=100'

curl 'https://api.pricemind.io/v1/channels/202/products/12345?include=offers' \
  --header "X-API-Key: $PRICEMIND_API_KEY"

curl --get 'https://api.pricemind.io/v1/channels/202/products/lookup' \
  --header "X-API-Key: $PRICEMIND_API_KEY" \
  --data-urlencode 'sku=ABC/001' --data-urlencode 'include=offers'

curl 'https://api.pricemind.io/v1/channels/202/products?include=offers&limit=25' \
  --header "X-API-Key: $PRICEMIND_API_KEY"

curl --get 'https://api.pricemind.io/v1/channels/202/offers' \
  --header "X-API-Key: $PRICEMIND_API_KEY" \
  --data-urlencode 'competitor_domain=shop.example' --data-urlencode 'limit=100'

curl --get 'https://api.pricemind.io/v1/channels/202/products/12345/offers' \
  --header "X-API-Key: $PRICEMIND_API_KEY" \
  --data-urlencode 'cursor=opaque-token'

For an offer detail, request its links.self. Offer IDs are opaque, versioned logical associations; they remain stable when a price record is replaced and never grant access by themselves. Product, offer, and price-record IDs are strings. Channel IDs are positive integers. Legacy product IDs are not required.

Own SKU and competitor SKU

Own SKU lookup is exact and case-sensitive within the authorized channel and its selected source. Leading zeroes, punctuation, and slashes are preserved. Use URL encoding or --data-urlencode. There is no global fallback.

A missing SKU returns 404; multiple products return 409 ambiguous_sku. A product list with the exact sku filter may return multiple items. The lookup response supplies the canonical product link.

Ambiguous SKU
{"error":{"code":"ambiguous_sku","message":"More than one product in this channel has the supplied SKU.","details":{"parameter":"sku"}}}

competitor_sku identifies the competitor listing and requires competitor_domain. Offer filters combine with AND: main_product_domain_id, competitor_product_domain_id, competitor_domain, and competitor_sku. The product-specific offer endpoint omits the redundant main-product filter. One competitor product may have several channel associations.

Unknown parameters, repeated scalar parameters, malformed IDs, unsupported include values, and cursor/filter mismatches return 400. Arbitrary datagrid filtering is not supported.

Traverse every selected record

Follow links.next until it is null. The envelope provides pagination.limit, has_more, and next_cursor; there is no total count. Products are ordered by numeric product-domain ID. Offers use a stable, unique association order.

Products without offers and flat offer lists default to 100 items and accept limits from 1 to 500. With include=offers, products default to 25 and accept up to 100. Each embedded offer page contains at most 20 offers and has its own continuation. You may change the allowed limit when continuing, while keeping filters and include values unchanged.

Product, nested offer, and flat offer traversal
const origin = 'https://api.pricemind.io';
const headers = { 'X-API-Key': process.env.PRICEMIND_API_KEY };

async function* pages(first) {
  let next = first;
  while (next) {
    const url = new URL(next, origin);
    if (url.origin !== origin) throw new Error('Unexpected continuation origin');
    const response = await fetch(url, { headers });
    if (!response.ok) throw new Error(await response.text());
    const page = await response.json();
    yield page.data;
    next = page.links.next;
  }
}

for await (const products of pages('/v1/channels/202/products?include=offers&limit=25')) {
  for (const product of products) {
    await saveProduct(product);
    for (const offer of product.offers.data) await saveOffer(offer);
    // Each product owns a separate embedded offer continuation.
    for await (const offers of pages(product.offers.links.next)) {
      for (const offer of offers) await saveOffer(offer);
    }
  }
}

// Or traverse all selected offers without requesting each product:
for await (const offers of pages('/v1/channels/202/offers?limit=100')) {
  for (const offer of offers) await saveOffer(offer);
}

Cursors are authenticated, opaque, and valid for 24 hours. Tampered or mismatched cursors return 400 invalid_cursor; expired cursors return 410 cursor_expired; a currently different selected source returns 409 source_changed. Cursors bind the selected source identity, not a durable source generation: an intervening A → B → A selection change is not guaranteed to invalidate them. Restart traversal with a fresh request after a source change or expiry. A valid product with no selected offers returns an empty OfferPage and 200. A missing or inaccessible resource returns 404.

Responses have a 3 MiB serialized JSON budget. Pages may contain fewer complete records than the requested limit. Descriptions, galleries, and attributes are never cut to fit. If one complete standalone resource exceeds the budget, the request returns 503 representation_unavailable with reason record_too_large, retaining that record's traversal position.

Catalog and current-price conventions

Every offer includes its own full available public catalog: title, URL, locale, description, brand, codes, categories, complete image gallery, typed collected attributes, known variant data, and entitled custom fields. Missing groups use null or empty values and field_status; known-empty collections are distinct from unknown data. An attribute or custom field with an unknown value retains its declared data_type and uses value: null; known decimal values remain exact strings. Categories contain a path only when collected hierarchy is known. Own catalog data follows the channel's selected source and existing field precedence; each competitor catalog comes from that listing's product identity. Descriptions, images, attributes, and related details are joined from existing collected catalog/source data even when the index did not copy them. Indexed channel prices and selected offers retain their existing business rules.

Canonical ean values and other codes remain strings. Money amounts remain decimal strings and are rounded half-up to two decimal places, matching Lobe customer-visible prices. Other decimal attributes retain their native precision; use a decimal library rather than binary floating-point arithmetic. regular, special, effective, and delivery each expose tax-exclusive and tax-inclusive amounts. tax_rate is a fraction, such as "0.20". Primary and split prices, and your own named prices, follow the existing channel-indexed representation. Named competitor prices are collected from existing price records and retain each record's declared price.currency, which can differ from the channel currency. No equivalent normalized named competitor fields exist in the current channel index, and this API does not compute a second FX conversion. Preserve the stored amount and inspect the currency before comparing named prices. No FX provenance is implied.

Null means unknown or unavailable; zero means a known zero. Failed observations never become zero-price placeholders. Effective price follows the channel's configured selection. Read effective_includes_delivery to determine delivery inclusion; do not add delivery twice or assume an invented landed total. Descriptions preserve available content. Their format is text or html only when source metadata explicitly declares it; otherwise it is null. Render unknown-format content safely and sanitize HTML before browser rendering.

Synthetic complete Product with Offer
{
  "data": {
    "channel_id": 202,
    "catalog": {
      "product_domain_id": "12345",
      "sku": "ABC/001",
      "title": "Synthetic example kettle",
      "url": "https://own.example/products/ABC-001",
      "locale": "en-GB",
      "description": {
        "format": "html",
        "content": "<p>Synthetic example description.</p>"
      },
      "brand": {
        "id": "17",
        "name": "Example Brand"
      },
      "codes": {
        "ean": [
          "0012345678905"
        ],
        "sku": [
          "ABC/001"
        ],
        "mpn": [
          "K-001"
        ]
      },
      "categories": [
        {
          "id": "12",
          "name": "Kettles",
          "path": [
            "Kitchen",
            "Appliances",
            "Kettles"
          ]
        }
      ],
      "images": [
        {
          "url": "https://own.example/images/kettle-front.jpg",
          "alt": "Front view",
          "width": 1200,
          "height": 1200
        },
        {
          "url": "https://own.example/images/kettle-side.jpg",
          "alt": null,
          "width": null,
          "height": null
        }
      ],
      "attributes": [
        {
          "name": "capacity",
          "label": "Capacity",
          "data_type": "decimal",
          "value": "1.500",
          "unit": "L"
        },
        {
          "name": "features",
          "label": null,
          "data_type": "array",
          "value": [
            "quiet",
            "automatic"
          ],
          "unit": null
        },
        {
          "name": "cordless",
          "label": "Cordless",
          "data_type": "boolean",
          "value": true,
          "unit": null
        }
      ],
      "variant": {
        "is_configurable": false,
        "parent_product_domain_id": null,
        "attributes": [
          {
            "name": "colour",
            "label": "Colour",
            "data_type": "string",
            "value": "Blue",
            "unit": null
          }
        ]
      },
      "custom_fields": [
        {
          "machine_name": "cost",
          "label": "Cost",
          "data_type": "decimal",
          "value": "65.000"
        }
      ],
      "updated_at": "2026-09-14T08:00:00Z",
      "field_status": {}
    },
    "price": {
      "currency": "EUR",
      "regular": {
        "excl_tax": "100.00",
        "incl_tax": "120.00"
      },
      "special": {
        "excl_tax": "90.00",
        "incl_tax": "108.00"
      },
      "effective": {
        "excl_tax": "90.00",
        "incl_tax": "108.00"
      },
      "delivery": {
        "excl_tax": null,
        "incl_tax": null
      },
      "tax_rate": "0.20",
      "effective_includes_delivery": false,
      "product_price_id": "998877",
      "observed_at": "2026-09-14T08:00:00Z",
      "stale_at": "2026-09-16T08:00:00Z"
    },
    "additional_prices": [],
    "availability": 1,
    "status": null,
    "quality": {
      "is_stale": false,
      "eligible_for_comparison": true,
      "reasons": []
    },
    "links": {
      "self": "/v1/channels/202/products/12345",
      "offers": "/v1/channels/202/products/12345/offers"
    },
    "offers": {
      "data": [
        {
          "offer_id": "v1.WzIwMiwiMTIzNDUiLCI2Nzg5MCIsInNob3AuZXhhbXBsZSIsInByaW1hcnkiLG51bGwsbnVsbF0",
          "channel_id": 202,
          "main_product_domain_id": "12345",
          "competitor": {
            "domain": "shop.example"
          },
          "product": {
            "product_domain_id": "67890",
            "sku": "SHOP-0001",
            "title": "Synthetic example kettle",
            "url": "https://shop.example/product/0001",
            "locale": "en-GB",
            "description": {
              "format": null,
              "content": "<p>Synthetic example description.</p>"
            },
            "brand": {
              "id": "17",
              "name": "Example Brand"
            },
            "codes": {
              "ean": [
                "0012345678905"
              ],
              "sku": [
                "SHOP-0001"
              ],
              "mpn": [
                "K-001"
              ]
            },
            "categories": [
              {
                "id": "12",
                "name": "Kettles",
                "path": [
                  "Kitchen",
                  "Appliances",
                  "Kettles"
                ]
              }
            ],
            "images": [
              {
                "url": "https://shop.example/images/kettle-front.jpg",
                "alt": "Front view",
                "width": 1200,
                "height": 1200
              },
              {
                "url": "https://shop.example/images/kettle-side.jpg",
                "alt": null,
                "width": null,
                "height": null
              }
            ],
            "attributes": [
              {
                "name": "capacity",
                "label": "Capacity",
                "data_type": "decimal",
                "value": "1.500",
                "unit": "L"
              },
              {
                "name": "features",
                "label": null,
                "data_type": "array",
                "value": [
                  "quiet",
                  "automatic"
                ],
                "unit": null
              },
              {
                "name": "cordless",
                "label": "Cordless",
                "data_type": "boolean",
                "value": true,
                "unit": null
              }
            ],
            "variant": {
              "is_configurable": false,
              "parent_product_domain_id": null,
              "attributes": [
                {
                  "name": "colour",
                  "label": "Colour",
                  "data_type": "string",
                  "value": "Blue",
                  "unit": null
                }
              ]
            },
            "custom_fields": [],
            "updated_at": "2026-09-14T08:00:00Z",
            "field_status": {}
          },
          "url": "https://shop.example/buy/0001",
          "relationship": {
            "kind": "primary",
            "match_source": "both",
            "selected_for_comparison": true,
            "seller_id": null,
            "seller_name": null,
            "split_criteria": null
          },
          "price": {
            "currency": "EUR",
            "regular": {
              "excl_tax": "100.00",
              "incl_tax": "120.00"
            },
            "special": {
              "excl_tax": "90.00",
              "incl_tax": "108.00"
            },
            "effective": {
              "excl_tax": "90.00",
              "incl_tax": "108.00"
            },
            "delivery": {
              "excl_tax": null,
              "incl_tax": null
            },
            "tax_rate": "0.20",
            "effective_includes_delivery": false,
            "product_price_id": "998877",
            "observed_at": "2026-09-14T08:00:00Z",
            "stale_at": "2026-09-16T08:00:00Z"
          },
          "additional_prices": [
            {
              "field_id": "91",
              "name": "Trade",
              "price": {
                "currency": "USD",
                "regular": {
                  "excl_tax": "100.00",
                  "incl_tax": "120.00"
                },
                "special": {
                  "excl_tax": "90.00",
                  "incl_tax": "108.00"
                },
                "effective": {
                  "excl_tax": "90.00",
                  "incl_tax": "108.00"
                },
                "delivery": {
                  "excl_tax": null,
                  "incl_tax": null
                },
                "tax_rate": "0.20",
                "effective_includes_delivery": false,
                "product_price_id": "998877",
                "observed_at": "2026-09-14T08:00:00Z",
                "stale_at": "2026-09-16T08:00:00Z"
              }
            }
          ],
          "availability": 1,
          "status": null,
          "quality": {
            "is_stale": false,
            "eligible_for_comparison": true,
            "reasons": []
          },
          "links": {
            "self": "/v1/channels/202/offers/v1.WzIwMiwiMTIzNDUiLCI2Nzg5MCIsInNob3AuZXhhbXBsZSIsInByaW1hcnkiLG51bGwsbnVsbF0"
          }
        }
      ],
      "pagination": {
        "limit": 20,
        "has_more": false,
        "next_cursor": null
      },
      "links": {
        "next": null
      },
      "meta": {
        "consistency": "live",
        "coverage": "selected_matched_offers"
      }
    }
  }
}

The downloadable OpenAPI schemas document the verified availability/status enum values, typed attribute unions, and closed quality reason codes: stale, scrape_failed, not_found, unavailable, missing_price, and unknown. Null is not false. Eligibility follows Lobe's business selection; a quality reason alone does not imply ineligibility.

Live data, freshness, and caching

These endpoints read the existing indexed channel membership, prices, and selected offers, enriched with currently available catalog/source records. Existing indexed products are readable immediately through Core API and the Lobe internal API. catalog.updated_at refers to existing catalog/source metadata when available; price.observed_at identifies the successful price observation; stale_at identifies the applicable freshness boundary. Quality can change as time passes.

The draft revision and published_at fields were removed because existing records do not provide a verified complete-response generation or timestamp. The response does not certify that catalog, prices, and offers came from one atomic indexing run, and a failed reindex does not promise preservation of an earlier complete response.

Pages report meta.consistency="live". Each representation is complete, but several requests do not form an immutable snapshot while catalog indexing or matches change. Static-data traversal is exhaustive without duplicates. Product-page coverage is channel_products; offer-page coverage is selected_matched_offers, including embedded pages.

The selected-offer scope preserves configured split, marketplace, and comparison rules. It does not browse an entire competitor catalog or every possible match. These endpoints read current prices; historical prices, bulk snapshot exports, and price writes use separate contracts. Without include=offers, the offers key is omitted and links.offers remains; omission does not mean no matches.

Conditional detail read
curl 'https://api.pricemind.io/v1/channels/202/products/12345' \
  --header "X-API-Key: $PRICEMIND_API_KEY" \
  --header 'If-None-Match: "etag-from-previous-response"'

Detail reads support ETags and 304 Not Modified. Responses use Cache-Control: private, no-cache: revalidate before reusing a stored customer response. Authentication, scopes, channel membership, and field permissions remain authoritative on every request. Lobe computes the full current representation before hashing it for an ETag; joined catalog, indexed price, selected-offer, visibility, and freshness changes affect conditional reads. The hash is not a monotonic revision or an indexing timestamp. Customer data must not be cached publicly or at a CDN.

Errors and retries

Read the structured error.code, message, and optional details. Keep the X-Request-ID header for support. Do not retry invalid input, permission failures, missing resources, or ambiguity unchanged.

400 / 401 / 403 / 404Invalid input, invalid credential, insufficient scope, or scoped resource absent.
409 / 410Ambiguous SKU or source change; expired cursor.
429Key quota reached. Respect Retry-After and rate-limit headers.
502 / 504Invalid upstream response or upstream failure; upstream timeout. Retry safe reads with bounded backoff and jitter.
503Required representation unavailable. Inspect the reason; record_too_large requires support or a representation change, rather than an endless retry.

Honor Retry-After when present. GET and conditional requests remain subject to the key's existing quota; pagination does not bypass it. See rate limits and errors.

Price precision and VAT

Money amounts are returned as decimal strings rounded half-up to two decimal places. Pricemind calculates with more precision than the API displays, then rounds tax-exclusive and tax-inclusive amounts independently.

€1.00 including 21% VAT
{
  "regular": {
    "excl_tax": "0.83",
    "incl_tax": "1.00"
  },
  "tax_rate": "0.21"
}

Why does 0.83 plus 21% not reproduce 1.00 exactly?

The unrounded tax-exclusive amount is approximately 0.826446. The API displays that amount as 0.83, while the intended tax-inclusive amount is displayed as 1.00. Recalculating from the already-rounded 0.83 introduces a second rounding step.

Which value should my integration use?

Use the returned incl_tax value when you need the tax-inclusive price and excl_tax when you need the tax-exclusive price. Do not reconstruct one displayed amount from the other. Use tax_rate as tax metadata rather than as a way to reverse the API's rounded output.