Start here when you need to preserve old URLs, connect products to other products, or maintain curated product sets.

Use this page to choose the right route before changing redirects, product relationships, or listing membership. For endpoint paths, request fields, response fields, enum values, status codes, and validation behavior, open the Redirects, Relations, Smart Listings, or Static Listings references.

The short model

Redirects preserve navigation from an old route or slug to the item that should now receive the shopper.

Product relations connect products to other products, such as accessories, alternates, upsells, or related items. Relation types classify those links.

Smart listings are rule-driven product lists. Preview the result set before you rely on it.

Static listings are manually curated product lists.

Use the area that matches the job:

• Use Redirects when the product, category, collection, or brand already exists and the work is preserving navigation.
• Use Relations when the product record stays the same but its relationship to other products changes.
• Use Smart Listings when membership is computed by rules and the result should be previewed.
• Use Static Listings when membership is manually curated.
• Use Search when the storefront needs discovery, facets, autocomplete, or relevance-driven result sets.
• Use Events when another system needs to react after redirect or relation changes.

Choose the right surface

Resolve redirects in a storefront context with Fetch redirects, Fetch redirects by item ID, or Fetch redirects by old slug. Shopper API redirect reads are for runtime lookup in app, store-group, market, and locale context.

Administer redirect records with List all app redirects, Create a new redirect, Update a redirect, or Delete a redirect. Use item-scoped routes such as List redirects for an item when a product, category, collection, or brand route has changed.

Define relationship classes with List all relation types in an app, Create a relation type, or Update a relation type. Relation types classify product-to-product relationships before relation records use them.

Create or inspect product relations with Create a product relation, Get a product relation, List all relations in an app, or List all relations for a product.

Attach or remove a product from a relation with Add a product to a relation or Remove a product from a relation.

Maintain rule-driven listings with Smart Listings reference and Preview smart listing results. Maintain curated lists with Static Listings reference.

Contract facts to keep in mind

Use these facts to choose the right reference. Use operation pages for exact fields, schemas, status codes, auth, and validation behavior.

• Choose by runtime. Browser-facing storefront code should use Shopper redirect reads and Search discovery. Trusted admin workflows should use Management API routes for redirect, relation, link, or listing records.
• Redirect create and update reject duplicate old-slug records and redirect chains in the same app/item/locale context.
• Relation types are app-scoped labels with title and type. Product relations use a relation type plus product membership.
• Removing a product from a relation deletes the whole relation when the relation would no longer have at least two products.
• Third-party links are app-level external resources with title, type, and url.
• Smart Listings are rule-driven variant lists. Create, update, and delete enqueue an app-level Smart Listing recomputation job.
• Static Listings are curated variant lists. Static Listing writes request product update publication for affected products.

MCP static-listing changes

MCP can preview and apply bounded static-listing work when an agent or operator needs a governed change flow for curated listing membership. Use it for static listing creation, replacement, and deletion.

Static-listing operations change the curated listing record and its variant membership. They do not own Smart Listing rules, Search ranking, product records, or variant records.

Create uses static-listing-create with a slug and 1-100 variant IDs. Preview rejects duplicate variant IDs and slug conflicts before a create or update can continue. Delete requires explicit no-rollback acknowledgement. Apply re-reads the preview assumptions, aborts when current evidence has drifted, writes through the matching static-listing operation, and records audit evidence.

Events

Use Events after redirect or product-relation changes. The Event catalog exposes redirect.created, redirect.deleted, product_relation.updated, product_relation.deleted, and product_relation_product.deleted.

The Event catalog does not expose a listing-specific event family. If another system needs listing changes, start with Smart Listings or Static Listings operation pages and decide whether the downstream system should poll or react to broader product updates.

Use the Event catalog for exact event type strings, schema IDs, required fields, and payload fields. Use Events latest for delivery and retry behavior.

Where to go next

• Need exact redirect contracts? Use Redirects reference.
• Need exact product-relation contracts? Use Relations reference.
• Need listing contracts? Use Smart Listings reference or Static Listings reference.
• Need product and variant context? Read Products, variants, variant groups, prices, and stock.
• Need storefront discovery? Start with Search latest.