Engineer Checklist: Delta API Canonical Enums for AI Inventory Signals

Inventory signals are the explicit availability and variant-level fields, in_stock, out_of_stock, preorder, backorder, or unknown, plus availability_date and stable item IDs, that AI shopping agents read to decide whether to show your product at all. The single fix that matters most: make the availability value in your feed match what a shopper sees on your landing page, using the exact enum spelling the agent expects every time stock changes.

TL;DR:

• Use exact accepted availability values on every variant; OpenAI rejects missing, empty, or invalid entries, and stable item and offer IDs preserve SKU tracking.
• Patch price and availability changes through the Delta API; reserve full SFTP uploads for new products or changes affecting the whole catalog.
• For preorder or backorder items, provide availability_date in ISO 8601 format, no more than one year ahead, and show it on the product page.
• Match feed availability to landing page structured data, and keep prices visible when products are out of stock because agents may compare both sources.
• After each update, confirm the processed product status is active; products marked out of stock remain ineligible until corrected and reprocessed.

Exact fields and values AI agents expect from your feed

AI shopping agents do not infer stock status from your website design or your marketing copy. They read a small set of structured fields, and if those fields are missing, misspelled, or inconsistent, the product row gets dropped before a shopper ever sees it.

The core fields merchants need to map correctly are availability (the status itself), an available boolean, availability_date, item_id, group_id, offer_id, and a variant_dict for products with options like size or color. OpenAI’s product feed specification requires an explicit availability value on every row, and accepts exactly five spellings: in_stock, out_of_stock, pre_order, backorder, or unknown.

Omitted, empty, or unrecognized availability values cause the entire product row to be rejected outright, which means the product simply never appears as a recommendation candidate.

A few mapping rules prevent most rejections:

• Use one row per variant rather than collapsing sizes or colors into a single listing.
• Keep item_id and offer_id stable across feed updates so the agent can track the same variant over time.
• Use group_id to tell the agent which rows belong to the same parent product.
• Keep option names (like “Size” or “Color”) spelled identically across every variant in a group.

Landing-page structured data should mirror the feed exactly. If your Schema.org markup says InStock while your feed says out_of_stock, agents that cross-check both sources will flag the mismatch and may suppress the listing rather than guess which one is correct.

What happens to serving when stock status changes

Marking a product out_of_stock does not just add a label. It actively removes the product from eligibility until the feed is reprocessed with a corrected status.

According to OpenAI’s Ads product-feeds guidance, an out_of_stock product stops qualifying for delivery and will not resume until it is returned to in_stock and reprocessed. The same logic applies broadly across agent platforms: availability is treated as a gate, not a hint. Feed-level settings and an is_ads_eligible flag can also control whether a product enters ad processing at all, separate from organic recommendation eligibility.

Most non-serving issues trace back to a short list of causes:

• An availability field left empty instead of set to unknown.
• A misspelled enum value, like “instock” instead of in_stock.
• A landing page that returns an error or missing image when the agent tries to verify the product.
• A filter or selector rule that excludes the product after a routine feed update.

Pro Tip: Keep the price visible on your landing page even when a product is out of stock. Google’s product data guidance requires this, and it also keeps the page usable for shoppers who land there from a cached agent response.

When to use Delta API versus a full SFTP upload

Not every inventory change needs the same update method, and using the wrong one is a common source of stale availability data.

OpenAI’s Ads product-feeds guidance recommends a clear split: use the Delta API or a PATCH request for price and availability changes, and reserve SFTP full uploads for adding new products or making bulk field changes across the catalog.

1. Patch availability and price through the Delta API whenever a SKU goes out of stock, comes back in, or changes price. This is the highest-leverage update for fast-moving inventory, since it reaches the live feed without reuploading everything.
2. Use SFTP full uploads when launching new products, restructuring variant groups, or changing fields that touch the whole catalog at once.
3. Set a cadence by catalog speed. Near-real-time deltas suit SKUs that sell out often; hourly or daily batch updates cover most catalogs; a nightly full refresh works as a fallback to catch anything the deltas missed.
4. Keep your source-of-truth inventory system in sync with delta patches. A mismatch between your internal stock count and what you’ve patched to the feed creates exactly the kind of inconsistency that gets rows flagged later.

After any update, verify it actually processed. Query the product and confirm the feed status response shows “active” rather than pending or rejected, since a patch that silently fails leaves the old, wrong availability value live.

How to confirm your inventory signals were ingested correctly

Pushing an update is not the same as confirming an agent sees it the way you intended. A short validation routine catches mismatches before they cost you visibility.

Start with the raw feed itself: pull a sample of rows and check that availability values use the exact accepted spellings, and that item_id and group_id values are stable across exports rather than regenerating on every sync.

Next, confirm processing on the platform side. Shopify’s Global Catalog documentation describes agent catalog responses that include inferred fields like available, status, and running_low, which developers can query directly to check whether a variant’s availability processed the way the feed intended.

A few checks worth running regularly:

• Compare the landing page’s visible price and Schema.org availability against the feed value for the same SKU.
• Use a UCP testing sandbox to send a product query and inspect the checkout URL and variant data an agent would actually receive.
• Watch for “status: active” confirmations in feed responses, and investigate any product that silently drops out after a routine update, since a filter rule is often the cause.

Pro Tip: Treat inferred fields from Shopify’s storefront catalog tools as a discovery signal, not a substitute for the availability and price data you provide directly.

Fast action checklist: fix the biggest issues this week

You don’t need a full re-platform to close most inventory-signal gaps. A focused week of fixes handles the issues that cause the most rejected rows and lost visibility.

1. Export a sample of product rows and check every availability value against the five accepted spellings: in_stock, out_of_stock, preorder, backorder, unknown.
2. Map your internal stock states to those canonical enums, then route price and availability changes through the Delta API instead of waiting for the next full upload.
3. Add availability_date in ISO 8601 format for any preorder or backorder item, and display that date on the landing page itself.
4. Query the processed product data and confirm the feed status reads “active.” Repeat the export-and-check cycle until no rows come back rejected.

This sequence targets the fixes with the fastest payoff first: canonical values and stable IDs, then update speed, then preorder handling, then verification. Each step closes a gap that otherwise silently removes products from consideration.

Definition and significance of inventory signals in AI contexts

In an AI shopping context, an inventory signal is any structured data point that tells a shopping agent whether a product can actually be bought right now, and under what conditions. That includes the availability enum, the available boolean, availability_date for items not yet shippable, and variant-level status for each size or color option.

These signals matter more in agent-driven shopping than they did in traditional search or display ads, because an agent is making a recommendation on a shopper’s behalf, often without the shopper browsing the page first. If the agent recommends a product that turns out to be out of stock, the failure is visible immediately and erodes trust in the agent’s suggestions, not just in your brand.

That dynamic pushes platforms toward stricter enforcement than older ecommerce feeds required. OpenAI’s product specification rejects rows with missing or malformed availability values outright, rather than defaulting to an assumed status. There is no “probably in stock” fallback.

For merchants, this reframes inventory data from a backend operations concern into a visibility concern. A product with excellent copy, strong images, and competitive pricing still won’t surface if its availability field is empty or misspelled. The signal itself has become a gating mechanism, which means getting it right is a prerequisite for every other optimization, not a parallel task.

How inventory signals impact AI-driven demand forecasting

Accurate, consistently updated availability data does more than keep a single product visible. It shapes how an agent, or the systems feeding recommendations to it, interpret demand patterns across a catalog over time.

When availability flips reliably and promptly between in_stock and out_of_stock, that pattern becomes a usable signal: frequent stockouts on a SKU suggest strong demand relative to supply, while a SKU that rarely moves out of in_stock suggests steadier, more predictable availability. Stale or inconsistent signals break that pattern. A product stuck showing in_stock after it actually sold out doesn’t just mislead the shopper, it muddies any downstream inference about how fast that item actually moves.

Preorder and backorder handling plays into this directly. Google’s Merchant Center guidance requires an availability_date in ISO 8601 format for preorder and backorder items, capped at up to one year out, specifically so systems reading the feed can distinguish “not available yet, but committed” from “simply out of stock with no plan.” That distinction carries real signal value: a backorder with a near-term date reads very differently from one with no date at all.

For merchants, the practical takeaway is that forecasting quality downstream depends on feed hygiene upstream. Delta updates applied promptly, rather than batched once a week, keep the signal fresh enough to reflect real demand rather than a lagging snapshot of it.

Best practices for integrating inventory signals with AI algorithms

The merchants who avoid most inventory-signal problems tend to follow a short set of habits rather than a complex system.

First, treat the feed as the single source of truth and push every change through it immediately, rather than updating the website first and the feed later. OpenAI’s Ads documentation specifies required columns including item_id, title, description, url, brand, image_url, price, and availability, and expects those fields to stay current through the Delta API rather than periodic exports.

Second, keep variant data consistent. Product fragment guidance from OpenAI recommends one row per variant with stable IDs and consistently named options across a group, since inconsistent naming (calling one variant’s color field “Color” and another’s “colour”) breaks the agent’s ability to group them correctly.

Third, never let the landing page and the feed diverge. Structured data on the page should state the same availability value as the feed, and the price should remain visible even when the item is unavailable, since several platforms reference that page state when verifying a feed claim.

Fourth, build update automation around inventory events rather than manual exports. A webhook that fires on stock-level changes and triggers a Delta API patch closes the gap between an item actually selling out and the feed reflecting that, which matters most for the SKUs that move fastest.

Common challenges and pitfalls in using inventory signals for AI

Most inventory-signal failures come from a small set of recurring mistakes rather than exotic edge cases.

The most common is leaving the availability field empty instead of explicitly setting it to unknown. OpenAI’s specification treats an empty value the same as an invalid one: the row gets rejected either way, so there’s no safe default to fall back on.

A close second is spelling drift. Internal systems often use labels like “Available,” “In Stock,” or “0” and “1” for boolean states, and a direct, unmapped export of those labels rarely matches the exact enums an agent requires. Any mapping layer between your inventory system and your feed needs to translate consistently, not just once at setup but every time a new status gets introduced internally.

Landing-page and feed mismatches cause a different kind of problem: the row might pass validation, but the agent’s cross-check against the page finds a contradiction and suppresses the listing anyway. This happens often with caching, where a feed update goes out immediately but the website’s product page caches an old availability state for minutes or hours.

Variant handling causes a less visible but costly issue. Merchants who collapse all variants into a single row, or who let item_id values regenerate on every export, make it difficult for an agent to track a specific SKU’s history, which can affect how confidently it gets recommended at all.

Finally, over-reliance on inferred fields is a growing pitfall. Platforms increasingly auto-generate supplementary data, but Shopify is explicit that inferred fields are discovery aids, not a replacement for merchant-provided availability and price data.

Case studies and examples of inventory signals working as intended

A few concrete scenarios illustrate how these mechanics play out in practice.

Consider a merchant running a flash sale on a limited batch of a popular SKU. As units sell, the internal inventory system drops to zero, but the merchant updates only the website, not the feed, and waits for the next scheduled full SFTP upload that night. For several hours, the agent continues treating the SKU as in_stock and keeps recommending it, leading to failed checkouts. Had the merchant routed that change through the Delta API the moment stock hit zero, the availability flip would have reached the agent within the normal patch cycle instead of waiting for a batch job.

A second case involves a preorder launch. A merchant sets availability to preorder but leaves availability_date blank, assuming the field is optional. Under Google’s Merchant Center rules, that omission is exactly the kind of gap that creates ambiguity for any system trying to decide whether the product is worth recommending now or later. Adding a correctly formatted ISO 8601 date and surfacing it on the landing page resolves the ambiguity and lets the preorder surface normally.

A third, more structural example: a multi-variant apparel line where each size used a different capitalization for the same color name across export cycles (“Navy” versus “navy”). The inconsistency didn’t trigger a rejection, since the field still had a value, but it fractured the variant group, so the agent saw what looked like separate, unrelated products instead of one item with size options. Standardizing option naming at the point of export resolved the fragmentation.

Expert perspective: prioritization when engineering bandwidth is limited

Most teams don’t have the bandwidth to fix everything at once, so sequencing matters more than completeness. Canonical availability mapping comes first: it’s the single fix that prevents outright rejection, and nothing else matters if the row never enters the system. Delta automation for your highest-velocity SKUs comes second, since that’s where stale availability costs the most in lost recommendations.

Resource-constrained teams should resist the urge to over-invest in enrichment (richer descriptions, expanded attributes) before the basics are solid. A consistent, correctly spelled availability value on every page beats a beautifully written listing that silently contradicts its own feed. Once the fundamentals hold, webhook-driven automation keeps them holding without ongoing manual work.

— Xhurian

How ecentic helps you close inventory-signal gaps faster

Finding a feed-to-page mismatch by manually cross-checking rows against landing pages takes hours a small team rarely has. We built our platform to simulate how ChatGPT, Gemini, Claude, and Perplexity actually evaluate your listings, so you see exactly where availability, variant data, or structured data breaks down before it costs you a recommendation.

Our diagnostics flag mismatched enums, missing availability_date fields, and feed-versus-page contradictions in plain English, then let you publish the fix directly to your ecommerce platform with one click. Start with a free scan or compare our plans on the pricing page to see which fits your catalog size.

FAQ

What are the accepted availability values for AI shopping feeds?

The accepted values are in_stock, out_of_stock, pre_order (or preorder), backorder, and unknown, and the field must contain one of these exact spellings. OpenAI’s product feed specification rejects any row with a missing, empty, or unrecognized availability value.

What’s the difference between the Delta API and SFTP uploads?

The Delta API is built for frequent, targeted changes like price or availability updates on individual products, while SFTP full uploads suit bulk changes or adding new products to the catalog. OpenAI’s Ads feed guidance recommends using deltas for fast-moving inventory and reserving full uploads for broader catalog changes.

Does marking a product out of stock remove it immediately?

Yes. An out_of_stock product stops qualifying for delivery and recommendation until it’s updated back to in_stock and reprocessed, according to OpenAI’s Ads documentation. There’s no grace period where an out-of-stock item continues surfacing normally.

How should preorder and backorder dates be formatted?

The availability_date field should use ISO 8601 format and can be set up to one year in advance, per Google’s Merchant Center product data specification. This date should also appear on the product’s landing page so shoppers see the same information the feed provides.

Can ecentic fix inventory-signal mismatches automatically?

Our platform diagnoses mismatches between your feed and landing pages and provides one-click publishing to apply corrected fields in Shopify or WooCommerce. Pricing starts with the Compete plan at $14.90 per month, with higher tiers available for larger catalogs.

Sources

• Products – Agentic Commerce | OpenAI Developers
• Product data specification - Google Merchant Center Help
• Global Catalog MCP | Shopify dev docs

Primary spec and documentation links for implementers

For edge cases and exact validation rules, go straight to the source documentation rather than relying on secondhand summaries. The OpenAI product feed spec and Ads product-feeds guidance cover required fields, enum values, and update channels in detail. Google’s Merchant Center help documents availability_date and landing-page matching rules, and Shopify’s Global Catalog docs explain how agent catalog responses handle inferred and variant-level availability. For implementing structured data alongside these feeds, this schema markup guide covers the types merchants typically need first.