Developer documentation

Inventory feed specification

This document defines the file format TexasGunFinder reads when pulling inventory from a dealer. Once configured, the feed keeps your listings on TexasGunFinder synchronized with the source of truth in your own inventory system.

Overview

Two feed formats are supported. Both map to the same internal schema; choose whichever your existing tooling produces more naturally.

• CSV — Google Merchant Center–compatible column layout with a small number of firearms-specific additions. Recommended when your point-of-sale or inventory system already exports a Merchant Center feed.
• JSON Feed 1.1 — standard JSON Feed 1.1 with a _tgf extension namespace for firearms-specific fields. Recommended for custom integrations.

Feeds are polled on a six-hour interval. Format is detected from the HTTP Content-Type response header, with a fallback to body inspection. The full transport contract is documented under Polling behavior.

CSV format

UTF-8 encoded, comma-separated, with a header row on the first line. Column names follow the Google Merchant Center specification where an equivalent field exists; firearms-specific columns (category_slug, city_slug, and others under optional columns) extend it.

Example

id,title,link,price,condition,availability,brand,mpn,image_link,additional_image_link,description,category_slug,city_slug,caliber,capacity,barrel_length,zip
SKU-001,"Sig Sauer P320 XCARRY 9mm 4.6"" 17rd",https://clarkssporting.com/inventory/12345,749.99 USD,new,in_stock,Sig Sauer,P320,https://clarkssporting.com/img/12345/main.jpg,https://clarkssporting.com/img/12345/side.jpg;https://clarkssporting.com/img/12345/back.jpg,New in box; X-Series slide; Romeo1 Pro plate,handguns,fort-worth,9mm,17,4.6,76102
SKU-002,Ruger 10/22 Carbine,https://clarkssporting.com/inventory/12346,349.00 USD,used,in_stock,Ruger,10/22,https://clarkssporting.com/img/12346.jpg,,Rimfire classic,rifles,austin,.22 LR,10,18.5,78701

Required columns

• id — stable seller SKU. Upsert key.
• title — listing title.
• link — public URL on your site.
• price — GMC format: "749.99 USD". Non-USD skipped.
• condition — new / like_new / used / refurbished.
• availability — in_stock or out_of_stock. Out-of-stock rows are ingested but marked inactive.
• category_slug — must match one of ours (see /sources or ask us for the full list).
• city_slug — Texas city. We auto-create rows for cities we haven't seen yet, but the slug format has to be URL-safe (lowercase, hyphens for spaces): fort-worth, san-antonio.

Optional columns

• description — plain text; 40 to 400 words recommended.
• image_link — primary image URL. Images are mirrored to our CDN on ingest; hotlink protection on your origin does not affect display.
• additional_image_link — additional image URLs, semicolon-separated per the GMC specification. Up to 7 accepted.
• brand, mpn, gtin — manufacturer identifiers.
• caliber, capacity, barrel_length, zip — firearms-specific metadata used for search and filtering.

JSON Feed 1.1 format

Standard JSON Feed 1.1 document. Firearms-specific fields are placed in a _tgf extension object at the item level, following the JSON Feed extension convention.

{
  "version": "https://jsonfeed.org/version/1.1",
  "title": "Clarks Sporting — Inventory",
  "home_page_url": "https://clarkssporting.com/",
  "items": [
    {
      "id": "SKU-001",
      "url": "https://clarkssporting.com/inventory/12345",
      "title": "Sig Sauer P320 XCARRY 9mm 4.6\" 17rd",
      "content_text": "New in box, X-Series slide, Romeo1 Pro plate.",
      "image": "https://clarkssporting.com/img/12345/main.jpg",
      "attachments": [
        {"url": "https://clarkssporting.com/img/12345/side.jpg", "mime_type": "image/jpeg"}
      ],
      "date_published": "2026-08-10T14:22:00Z",
      "_tgf": {
        "price_cents": 74999,
        "category_slug": "handguns",
        "city_slug": "fort-worth",
        "zip": "76102",
        "brand": "Sig Sauer",
        "mpn": "P320",
        "caliber": "9mm",
        "capacity": "17",
        "barrel_length": "4.6",
        "condition": "new",
        "availability": "in_stock"
      }
    }
  ]
}

JSON field mapping

• Required at the item level: id, title, url.
• Required under _tgf: price_cents (integer, NOT dollars), category_slug, city_slug.
• Optional: everything else (see the CSV list).

Polling behavior

User agent

Requests are sent with User-Agent: TexasGunFinderBot/1.0 (+https://texasgunfinder.com/get-listed/feed-spec/). Please permit this user agent in any WAF, bot-management, or robots.txt rules that apply to the feed URL.

Interval

A minimum of six hours between polls per feed. Our scheduler wakes hourly to check for feeds that are due, but no feed is fetched more often than the six-hour floor.

Format detection

Determined from the Content-Type response header (text/csv or application/json). If the header is absent, the first non-whitespace byte of the body is inspected.

Deletions

Items present in a prior poll but absent from the current poll are marked inactive. Re-adding the item to a subsequent feed reactivates the listing without loss of history.

Failure handling

A malformed feed body causes the poll to fail with no changes applied. Previously ingested listings remain unchanged. Ten consecutive failures automatically disable the feed and notify the dealer contact on file.

Validation errors

Row-level validation errors are surfaced in the dealer dashboard under the feed status panel.

unknown category_slug

The value does not match a recognized category. Contact support for the current allowlist.

unknown city_slug

The value does not match a known Texas city. Slugs must be lowercase, hyphen-separated (for example, fort-worth).

missing or invalid price

CSV requires "749.99 USD"; JSON requires an integer _tgf.price_cents. Non-USD currencies are not supported.

Support

For integration questions, contact [email protected]. If you are not yet a TexasGunFinder dealer, begin with the dealer application form.