> ## Documentation Index > Fetch the complete documentation index at: https://crushrewards.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Find the best price for a product across retailers > Returns a nullable `gpc` block identifying the resolved product's GS1 GPC product type (code, title, full ancestry, and how exact the mapping is) — null when the product's category has no GPC mapping. Find the lowest current price for a product across retailers in US and Canada. Cross-retailer comparison is entity-matched (barcode-anchored resolution links the same physical product across platforms). Returns the cheapest option plus other retailer prices for comparison. Every price row is labeled match_type: 'entity' (verified same product) or 'title' (text match — may be a variant on broad queries); pass strict=true to restrict the comparison to entity-verified rows only. Comparison rows carry observed_at so mixed-vintage prices are distinguishable. ## OpenAPI ````yaml https://api.syntalic.com/openapi.json get /v1/shopper/best-price openapi: 3.1.0 info: title: 'Syntalic — Data Analytics for Agentic Commerce ' version: 1.0.0 contact: name: Syntalic email: support@syntalic.com url: https://syntalic.com description: >- Competitive pricing data across US and Canadian e-commerce retailers (Amazon, Walmart, Target, Best Buy, Home Depot, etc.). Serves price comparisons, deal alerts, brand tracking, promotional intelligence, and market analytics to AI agents via x402 and MPP micropayments. x-guidance: >- This API has three endpoint groups organized by use case: **Shopper endpoints** ($0.01/query): Use these for price comparisons and deal hunting. Start with /v1/shopper/best-price?q= to find the cheapest option across retailers. Use /v1/shopper/deal-finder?category= to find discounted products. Use /v1/shopper/price-drop-alert?q= to check for recent price drops. **Marketing endpoints** ($0.01/query): Use these for competitive analysis. /v1/marketing/competitive-landscape?category= shows all products in a category with pricing. /v1/marketing/brand-tracker?brand= tracks a brand's pricing over time. /v1/marketing/share-of-shelf?category= shows brand market share. **Analyst endpoints** ($0.02/query): Use these for market-level insights. /v1/analyst/inflation?category= shows price trends over time. /v1/analyst/price-dispersion?category= shows price spread across retailers. All endpoints accept an optional 'country' parameter (us or ca, defaults to us). Query parameters use 'q' for free-text search and 'category' for category-level queries. Marketing and analyst responses carry a `meta` block (served_from, freshness_seconds, schema_version) for staleness budgeting and a `resolved` block describing how the category input was matched against the taxonomy. Every response also sends an X-Data-Freshness-Hours header. **Free pre-payment rejection:** requests that cannot be served are rejected BEFORE any payment challenge — invalid params (400 INVALID_PARAMS), retailers that are not serving-eligible (404 RETAILER_NOT_SERVING_ELIGIBLE, with the catalog quality status and the serving_eligible_retailers list in error.details), and shopper queries that resolve to nothing in the catalog (404 NO_RESULTS). You only pay when the API can actually execute your query. Retailer values are case-insensitive (amazon == Amazon). servers: - url: https://api.syntalic.com security: [] paths: /v1/shopper/best-price: get: tags: - Shopper summary: Find the best price for a product across retailers description: >- Returns a nullable `gpc` block identifying the resolved product's GS1 GPC product type (code, title, full ancestry, and how exact the mapping is) — null when the product's category has no GPC mapping. Find the lowest current price for a product across retailers in US and Canada. Cross-retailer comparison is entity-matched (barcode-anchored resolution links the same physical product across platforms). Returns the cheapest option plus other retailer prices for comparison. Every price row is labeled match_type: 'entity' (verified same product) or 'title' (text match — may be a variant on broad queries); pass strict=true to restrict the comparison to entity-verified rows only. Comparison rows carry observed_at so mixed-vintage prices are distinguishable. operationId: getBestPrice parameters: - name: q in: query required: false schema: type: string minLength: 1 description: >- Search query (product name, keyword, or brand + model). Required unless `product_uid` or `entity_uid` is supplied. example: airpods - name: product_uid in: query required: false schema: type: string minLength: 1 description: >- Stable product identifier returned by a prior Syntalic shopper response. When supplied, the endpoint should pin to this listing instead of re-resolving free text. example: p_airpods_deal - name: entity_uid in: query required: false schema: type: string minLength: 1 description: >- Stable cross-retailer entity identifier returned by a prior Syntalic shopper response. When supplied, the endpoint should resolve within the same physical-product entity. example: e_airpods_deal - name: country in: query required: false schema: type: string enum: - us - ca default: us description: Country (us or ca) example: us - name: retailer in: query required: false schema: type: string enum: - amazon - walmart - target - bestbuy - homedepot - costco - ikea - samsclub - cvs - dillards description: >- Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted) example: amazon - name: limit in: query required: false schema: type: integer default: 10 minimum: 1 maximum: 50 description: Max results to return (default 10, min 1, max 50) example: 10 - name: strict in: query required: false schema: type: boolean default: false description: >- When true, restrict the comparison to entity-verified listings of the matched product (match_type 'entity' only). Default false also includes title-match rows — useful for broad queries, but may mix product variants. example: false responses: '200': description: Best price result content: application/json: schema: type: object properties: query: type: string dropped_terms: type: array items: type: string nullable: true description: >- Non-null when no product matched the query as written and retrieval had to drop these trailing terms to resolve one. Treat the result as an answer to the SHORTENED query: `NOBULL Laces black` returning these terms as ['black'] means the black variant was not found, only NOBULL Laces. country: type: string currency: type: string product_uid: type: string entity_uid: type: string nullable: true scope: type: string enum: - entity - listing description: >- 'entity' = prices span the resolved product's cross-platform entity; 'listing' = the product belongs to no multi-member entity, so only its own listing is priced. member_count: type: integer match_suspect: type: boolean description: >- True when the pipeline has already flagged this entity as welding together materially different products (intra_entity_incoherent). The comparison set — and therefore the headline price — may span variants that are not substitutes; prefer strict=true or a product_uid when this is set. retailers_compared: type: integer description: >- Distinct retailers spanned by best_price + other_prices. **1 means no cross-retailer comparison was possible for this product** — it is the cheapest listing found, not the cheapest anywhere. Most direct-to-consumer products are sold by a single merchant and can never exceed 1; named-retailer products are roughly 48x likelier to support a real comparison. related_matches are excluded from this count because they are title matches on other entities, not prices for this product. resolved_product: type: object additionalProperties: true gpc: type: object additionalProperties: true nullable: true best_price: type: object properties: product_uid: type: string entity_uid: type: string product_name: type: string retailer: type: string price: type: number list_price: type: number nullable: true savings_pct: type: number nullable: true in_stock: type: boolean nullable: true condition: type: string enum: - new - refurbished - used - unknown description: >- Derived from product name + retailer URL signals (e.g. Walmart 'Restored', Amazon Renewed). Defaults to 'new' when no condition signal is present. match_type: type: string enum: - entity - self_text - title description: >- 'entity' = verified same physical product via cross-platform entity resolution; 'self_text' = the resolved product itself, matched on its own text; 'title' = text match (may be a variant on broad queries). scraped_at: type: string format: date-time other_prices: type: array items: type: object properties: product_uid: type: string entity_uid: type: string retailer: type: string product_name: type: string price: type: number in_stock: type: boolean nullable: true condition: type: string enum: - new - refurbished - used - unknown match_type: type: string enum: - entity - self_text - title observed_at: type: string format: date-time description: >- When this row's price was observed — rows in one comparison can differ in vintage. related_matches: type: array description: >- Title-matched rows OUTSIDE the resolved entity. Not price comparisons for the same product — a cheaper row here may be a different product, and a genuinely identical SKU can also land here when entity resolution split it across retailers. items: type: object properties: product_uid: type: string entity_uid: type: string nullable: true retailer: type: string product_name: type: string price: type: number in_stock: type: boolean nullable: true condition: type: string enum: - new - refurbished - used - unknown match_type: type: string enum: - entity - self_text - title observed_at: type: string format: date-time meta: type: object properties: served_from: type: string freshness_seconds: type: number schema_version: type: string computed_at: type: string format: date-time price_observed_at_min: type: string format: date-time nullable: true price_observed_at_max: type: string format: date-time nullable: true additionalProperties: true '400': description: >- Invalid query parameters or unsupported enum values. Rejected by preflight BEFORE the payment challenge — no payment is requested or charged for malformed requests. content: application/problem+json: schema: type: object required: - type - title - status properties: type: type: string format: uri-reference title: type: string example: Bad Request status: type: integer const: 400 detail: type: string instance: type: string error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true additionalProperties: true additionalProperties: true '402': description: Payment challenge required before executing paid work content: application/problem+json: schema: type: object required: - type - title - status properties: type: type: string format: uri-reference title: type: string example: Payment Required status: type: integer const: 402 detail: type: string instance: type: string error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true additionalProperties: true additionalProperties: true '404': description: >- No matching result. error.code distinguishes the cases: NO_RESULTS (the query resolves to nothing in the catalog), RETAILER_NOT_SERVING_ELIGIBLE (the requested retailer exists but is not serving-eligible — error.details carries its catalog quality_status and the serving_eligible_retailers list to retry against), or NOT_PUBLISHED (a social rollup the current publish run does not compute yet — a gap in what we publish, not a finding about the category). Structurally-unservable requests are rejected by preflight before any payment challenge. content: application/problem+json: schema: type: object required: - type - title - status properties: type: type: string format: uri-reference title: type: string example: Not Found status: type: integer const: 404 detail: type: string instance: type: string error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true additionalProperties: true additionalProperties: true '429': description: Rate limit exceeded content: application/problem+json: schema: type: object required: - type - title - status properties: type: type: string format: uri-reference title: type: string example: Too Many Requests status: type: integer const: 429 detail: type: string instance: type: string error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true additionalProperties: true additionalProperties: true '500': description: Unexpected server error content: application/problem+json: schema: type: object required: - type - title - status properties: type: type: string format: uri-reference title: type: string example: Internal Server Error status: type: integer const: 500 detail: type: string instance: type: string error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true additionalProperties: true additionalProperties: true ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.