How to Prepare Your Product Catalog for Claude Commerce Agents

Preparing a catalog for a Claude Commerce Agent is not an exercise in rewriting every product description. It is the work of defining a reliable contract between the agent’s tools and the systems that hold product and commercial truth.

This guide turns that contract into ten readiness layers. For each layer, document the current source, target representation, validation rule, freshness expectation, and owner. Start with a representative slice of the catalog rather than attempting a full migration before you can test the contract.

Define the agent actions first

List what the agent may do and classify each action as read, propose, approve, execute, or reverse. “Find a compatible item” and “change a product price” have very different data, freshness, and control requirements.

1. Product identity

Question: Does one real-world product resolve to one canonical entity?

Build stable identities above source-system record IDs. Retain manufacturer, MPN, GTIN where available, source identifiers, and the evidence supporting each match. Candidate generation, normalized comparison, contradiction detection, calibrated confidence, and human review should be separate stages.

Acceptance criteria: duplicate products do not split facts or performance; distinct products are not collapsed; every source record maps to a canonical entity or an explicit unresolved state.

2. Families and variants

Question: Can the agent distinguish family, model, variant, sellable SKU, offer, and pack?

Define which attributes create a variant in each category. Color may distinguish apparel variants; voltage, thread, bore, capacity, or region may distinguish industrial models. Connect the canonical model to the exact purchasable SKU and packaging level.

Acceptance criteria: a tool response never mixes specifications from a family page with price and stock from an unspecified variant. Cart actions always include the sellable identifier, quantity, and unit.

3. Decision-critical attributes

Question: Are the fields used to accept or reject a product typed and normalized?

Inventory the questions buyers actually ask. Map each to a schema field with data type, unit dimension, vocabulary, cardinality, category applicability, and validation rules. Preserve source values alongside normalized values.

Acceptance criteria: filters and comparisons operate on typed values; unknown is distinct from false or not applicable; dimensions cannot silently mix product and package measurements.

4. Relationships

Question: Are compatibility, substitutes, supersessions, bundles, and required accessories explicit?

Model relationships as typed edges with direction, conditions, scope, evidence, and validity dates. “Often bought together” is not the same as “required for operation”; a similar item is not necessarily an approved substitute.

Acceptance criteria: the agent can explain why a relationship applies and abstains when compatibility evidence is missing or ambiguous.

5. Price

Question: Is current commercial truth available for this buyer, channel, currency, unit, and time?

Separate list price from calculated customer price. Include currency, tax convention, price basis, unit, minimum quantity, tier, customer or segment scope, effective period, and promotion interactions. Call the pricing service when the result depends on transactional logic.

Acceptance criteria: the price is attached to the exact offer and quantity; the agent rechecks it before a transaction; expired promotions cannot leak from cached content.

6. Inventory and fulfillment

Question: Is availability fresh enough for the promised action?

Expose available-to-promise rather than an unexplained stock number where possible. Include location, quantity basis, reservation behavior, lead time, cutoff, delivery scope, and timestamp.

Acceptance criteria: freshness has a service-level objective; stock is revalidated for cart or order actions; an unavailable item triggers an approved substitute workflow rather than invention.

7. Policies

Question: Can shipping, returns, restrictions, and eligibility be evaluated without interpreting prose?

Keep customer-facing policy prose, but expose machine-evaluable predicates and outcomes to tools. Version the policy and return the rule identifier used in a decision. Examples include hazardous shipping restrictions, final-sale status, geographic eligibility, age restrictions, and return windows.

Acceptance criteria: the same inputs produce the same policy outcome; the response identifies the applicable rule and effective version.

8. Provenance and validation

Question: Can an important fact be traced to evidence?

For specifications and relationships, retain source, revision, location, captured value, normalized value, transformation, confidence, validation results, conflicts, reviewer decision, and timestamps. Define source authority per attribute rather than assuming one system is authoritative for everything.

Acceptance criteria: reviewers can reproduce a value; conflicting evidence remains visible; unsupported facts are withheld or labeled rather than converted into certainty.

9. Permissions and safe writes

Question: What may the merchant agent propose, approve, change, and reverse?

Enforce access outside the prompt. Use least-privilege tool scopes, explicit parameters, dry-run responses, approval records, idempotency keys, current-state checks, limits, and complete before-and-after audit logs.

Acceptance criteria: the model cannot promote its own proposal into an approval; every mutation is attributable and reversible.

10. Freshness and feedback

Question: What happens when supplier or operational data changes tomorrow?

Assign freshness policy by field. Stable attributes may refresh on source revision; inventory may expire in minutes. Track source arrivals, evidence changes, validation failures, downstream write status, and stale derived values.

Capture agent outcomes as structured signals: no-result queries, abandoned recommendations, corrections, rejected merchant proposals, substitutions, returns, and policy blocks. Use those signals to prioritize catalog fixes, not as permission to overwrite facts automatically.

Acceptance criteria: every agent-facing value has a freshness state; dependency tracking identifies what must be revalidated after a source change.

Build the tool response around the contract

Do not dump the full PIM record into context. Return the smallest response that supports the action, with stable semantics:

{
  "productId": "prod_1842",
  "variantId": "var_230v_blue",
  "sellableSku": "SKU-1842-B-230",
  "facts": [
    {
      "name": "rated_voltage",
      "value": 230,
      "unit": "V",
      "sourceId": "datasheet_rev_4",
      "verifiedAt": "2026-09-07T14:00:00Z"
    }
  ],
  "offer": {
    "currency": "EUR",
    "unitPrice": 89.5,
    "packQuantity": 1,
    "availableToPromise": 14,
    "observedAt": "2026-09-08T11:32:00Z"
  },
  "warnings": [],
  "freshness": "current"
}

Names and fields will differ by business. The principles should not: resolved entity, typed facts, scoped offer, evidence, timestamp, and explicit warnings.

Readiness scorecard

Score each layer from 0 to 3: 0 absent, 1 inconsistent, 2 defined but incomplete, 3 measured and enforced. Do not average away a blocking weakness. A zero in variant identity, transactional freshness, policy enforcement, or write permissions should block the affected production action.

• Every sampled source record resolves to a canonical product or an explicit unresolved queue.
• Variant-defining attributes and sellable packaging levels are documented by category.
• Decision fields have types, units, vocabularies, validation rules, and owners.
• Compatibility and substitution claims carry typed relationships and evidence.
• Price and availability are scoped and revalidated at action time.
• Policies are machine-evaluable and versioned.
• High-impact facts can be traced to sources and conflicts.
• Write tools separate proposal, approval, execution, and reversal.
• Freshness SLOs and stale-state behavior are defined by field.
• Agent outcomes feed a measured catalog-improvement queue.

Next, validate the implementation with the 20 production failure cases rather than only happy-path prompts. For the architectural rationale, read what a catalog must provide to Claude Commerce Agents.

FAQ