> ## 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. # Measure out-of-stock rates by retailer or category > Out-of-stock rate by retail chain or by category root - an on-shelf availability read rather than a pricing one. Answers 'which retailers are running out of stock', 'what is the stockout rate in this category', and 'is my brand actually on shelf'. Pivot with aggregate_by: 'seller' (default) ranks chains, 'category_root' ranks categories. The denominator is rows where availability was actually OBSERVED, never all rows: roughly 40% of listings carry no availability signal, and counting those as in-stock would report a healthy shelf whenever coverage is poor. availability_coverage reports what share of the scoped shelf carried a signal, so you can tell a genuine 5% stockout rate from one computed over a tenth of the listings. Groups with fewer than five observed rows are dropped rather than shown with a caveat - a rate from two rows is noise wearing a percentage sign. Unlike the pricing endpoints this one does NOT exclude price-flagged rows: the flag marks an untrustworthy price, not an untrustworthy listing, and dropping those rows would understate a chain's stock coverage for an unrelated reason. At least one of category or brand is required. ## OpenAPI ````yaml https://api.syntalic.com/openapi.json get /v1/marketing/availability-index 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/marketing/availability-index: get: tags: - Marketing summary: Measure out-of-stock rates by retailer or category description: >- Out-of-stock rate by retail chain or by category root - an on-shelf availability read rather than a pricing one. Answers 'which retailers are running out of stock', 'what is the stockout rate in this category', and 'is my brand actually on shelf'. Pivot with aggregate_by: 'seller' (default) ranks chains, 'category_root' ranks categories. The denominator is rows where availability was actually OBSERVED, never all rows: roughly 40% of listings carry no availability signal, and counting those as in-stock would report a healthy shelf whenever coverage is poor. availability_coverage reports what share of the scoped shelf carried a signal, so you can tell a genuine 5% stockout rate from one computed over a tenth of the listings. Groups with fewer than five observed rows are dropped rather than shown with a caveat - a rate from two rows is noise wearing a percentage sign. Unlike the pricing endpoints this one does NOT exclude price-flagged rows: the flag marks an untrustworthy price, not an untrustworthy listing, and dropping those rows would understate a chain's stock coverage for an unrelated reason. At least one of category or brand is required. operationId: getAvailabilityIndex parameters: - name: category in: query required: false schema: type: string minLength: 1 description: >- Product category. Accepts a human-readable name (e.g. 'electronics', 'beauty') or a taxonomy slug path (e.g. 'electronics/headphones'); matched against the catalog's category tree (exact node, subtree, or path substring). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'. example: electronics - name: brand in: query required: false schema: type: string minLength: 1 description: Brand name (e.g., Sony, Samsung, Nike) example: Apple - name: country in: query required: false schema: type: string enum: - us - ca default: us description: Country (us or ca) example: us - name: aggregate_by in: query required: false schema: type: string enum: - seller - category_root default: seller description: 'Dimension to group by: retail chain (default) or category root.' responses: '200': description: Availability index content: application/json: schema: type: object properties: category: type: string nullable: true brand: type: string nullable: true country: type: string aggregate_by: type: string enum: - seller - category_root groups: type: array items: type: object properties: key: type: string oos_rate: type: number example: 12.5 out_of_stock_count: type: integer observed: type: integer availability_coverage: type: number example: 0.6 coverage: type: object description: >- How much data backed this answer. `sufficient` is false when the slice is too thin to read as a market statement; the count is always reported so you can judge for yourself, and `note` explains an empty or thin result rather than leaving you to infer it. properties: products: type: integer example: 42 sufficient: type: boolean example: true note: type: string unpublished_note: type: string description: >- Names columns that came back null on EVERY row because the publish job writes them unpopulated, not because the subjects lack the attribute. Never infer a zero or an absence from a column named here. sku_note: type: string description: >- Present when `skus` is null on every row returned. Read the column as unavailable for this run, not as a stocking fact. rank_note: type: string description: >- Present when brands carry `tied_with`. Says how many, and that the tie list is pairwise proximity rather than an equivalence class. additionalProperties: true freshness: type: object description: >- How current the underlying observations are. `observedThrough` is the newest observation behind this answer; `staleHours` is its age. Both null when nothing was observed. properties: observedThrough: type: string format: date-time nullable: true staleHours: type: number nullable: true example: 6.5 additionalProperties: true quality: type: object additionalProperties: true nullable: true resolved: type: object properties: input: type: string category_path: type: string nullable: true department: type: string nullable: true match_source: type: string nullable: true match_confidence: type: number nullable: true alternates: type: array items: type: object additionalProperties: true additionalProperties: true 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 ````