commercetools AI Hub product feeds

commercetools AI Hub product feeds

AI Hub feeds go to several vendors: OpenAI Commerce feed (ChatGPT shopping), OpenAI Ads feed, Google Merchant Center and Microsoft Merchant Center. "AI Hub" names the whole export, not one vendor.

aihub_feeds.py fetch     commercetools          ─► <run>/raw/                 products, categories, Store, manifest
aihub_feeds.py build     raw + mapping + specs  ─► <run>/working/<vendor>-working.csv, report/, NEXT-STEPS.md
   (business team completes the working files offline)
aihub_feeds.py finalize  completed file         ─► <out>/<vendor upload file> + finalize report

Data integrity: commercetools is the only source of product data

Feeds are checked against the storefront, and a guessed value hides a real gap. So:

• Do not write, rewrite, shorten, translate, summarise or infer product content: titles, descriptions, brands, GTINs, MPNs, categories, colors, sizes, conditions, availability, prices or images. Not in mapping.json, not in the working files, not in the completed file.
• mapping.json changes only where a value is read from (attribute names, category and Store fields, id strategy) and how an existing value is spelled for a vendor (valueMaps, units, separators). It holds no values of its own.
• Feed eligibility flags are merchant settings, not product data, and the only defaults: discovery on (is_eligible_search=true), checkout off (is_eligible_checkout=false) and, for the OpenAI Ads feed only, is_ads_eligible=true. A product attribute overrides them; change a default only when the user asks. Google and Microsoft have no checkout flag; their products are listed for discovery by default.
• Storefront URL, seller name and policy URLs (privacy, terms, refund) come from the Store passed with --store, the Store whose product selections define the assortment.
• Values the business team adds in the working file are theirs. Convert the completed file as it is: finalize changes the format, never the content. If a value looks wrong, report it; do not correct it.

Before you start

1. Docs search (required, run first) — The first time you use this skill in a session you must run this before answering. It gathers the latest verified documentation as your primary grounding, filtered to the products this skill covers. Use this script for documentation search while working with this skill; the Knowledge MCP covers everything else. Always confirm details against retrieved documentation rather than the skill text alone:

   node "<this skill's directory>/scripts/docs-search.mjs" \
     --query "<extract key terms: AI Hub, product feed, Product Projections, price selection, Product Selections>" \
     --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
     --model "<current-model>" \
     --commercetools-project-key "<if known>" \
     --commercetools-region "<if known>" \
     --limit 10
   
   Pass the commercetools project key and region (as in api.{region}.commercetools.com) only if already in your context; otherwise omit both. Never search files or ask the user for them.
2. Vendor specs change often, which is why they are read at runtime. When the user asks whether a spec changed, or a vendor flags a field the report marked valid, rebuild the run with --specs live and report its Changes since the previous spec section. If a spec page could not be read, the report says which fallback was used and links the page.

Workflow

1. Agree the selection and market. Collect, asking only for what is missing:
   • credentials: a dotenv file with the CTP_* variables. Pass it with --env-file and never print or copy secret values;
   • Store, currency, country, distribution channel, locale. aihub_feeds.py fetch --list-stores prints the project's currencies, countries, languages and channels and every Store with its languages, countries, channel keys, product selections and storefront fields;
   • filters: any combination of product selections, categories, product types, SKUs, product keys, attribute conditions (--attribute color=blue), query predicates (--where) and search filters (--search-filter, e.g. inventory or price ranges). --list-categories and --list-attribute map the user's wording to keys. When wording could mean different data (stock as inventory or as an attribute), show both counts and ask;
   • vendors: the user names them; if the request does not say, ask, for example "Which vendors should I build feeds for: OpenAI Commerce feed, OpenAI Ads feed, Google Merchant Center, Microsoft Merchant Center?" Never assume all of them, and do not label one vendor "AI Hub". build requires --vendors (openai, openai-ads, google, microsoft);
   Flags, scopes and filter recipes: references/selecting-products.md.
2. Resolve, then download. Run aihub_feeds.py fetch --dry-run first. It writes nothing, shows what each name resolved to, counts matching products, samples whether they are in the Store assortment, and checks the feed locale against the data. Show the user the plan and any warnings, then run the download once they confirm. A name that matches several categories stops with the candidates: ask which one is meant (a dry run over the union shows whether the choice changes the result). Ignoring the Store assortment changes the scope, so ask before using --ignore-assortment.
3. Build the working files. aihub_feeds.py build --run <run> --vendors <named vendors> writes one working file per requested vendor, report/gap-report.md (required fields per vendor first), report/issues.csv and NEXT-STEPS.md. The first build writes <run>/mapping.json.
4. Review the gaps with the user. For each vendor, report which required fields are filled and which are missing, with example SKUs, and the ⚠? fields whose spec condition may apply (e.g. required for apparel) for the user to judge. Sort gaps into:
   • mapping gaps, where the value exists in commercetools under another name or spelling: point attributes.* (or store.*, categoryFields) at it, or add a valueMaps entry. Confirm with the user, rebuild offline, show before/after counts. See references/mapping-and-files.md;
   • values commercetools does not have: they stay blank in the working file, marked in _missing_required. The team fills them in the file or in commercetools.
5. Hand over the working files. Point to working/ and NEXT-STEPS.md: how to edit the files safely (import as text so GTINs and SKUs keep their form, keep the header row) and what each helper column means.
6. Finalize a completed file. When the user hands a completed file back, run aihub_feeds.py finalize --vendor <v> --input <file> --out <dir> (Google and Microsoft: --kind supplemental|primary, optional --columns). When the user wants an upload file straight away, finalize the generated working file as it is. Report the finalize report as facts: rows, required fields still missing or invalid, empty cells in supplemental columns, columns a vendor does not accept. Then give the vendor's upload guidance from its reference. Do not decide for the user whether to upload.

Facts to surface (information, not decisions)

Reference index

Scope

Checklist

• The vendors were named by the user (asked when missing, listing OpenAI Commerce feed, OpenAI Ads feed, Google and Microsoft), and only those were built.
• Flags stayed at their defaults (discovery on, checkout off, ads on only for the OpenAI Ads feed) unless the user asked otherwise.
• The selection, Store, currency, country and locale were confirmed with the user, and the dry run resolved every product selection, category and product type.
• The download used an API client with view_products and view_categories (plus view_product_selections / view_stores when used), and no secret was printed.
• Per vendor, the user knows which required fields are filled and which are missing, with example SKUs. Mapping gaps were fixed in mapping.json with the user's agreement.
• No product content was written or inferred; mapping.json only points at attributes and fields; the completed file was converted without changing its values.
• The report says which spec was used per vendor (live with fetch time, or the built-in list when the fetch failed); new or removed spec fields were mentioned.
• The user has the working files, NEXT-STEPS.md, the finalize report when a completed file was converted, and the upload guidance for each vendor.