Product Card Definitions Reference
Product Cards
Create reusable product card definitions for recommendation and merchandising experiences.
Audience: Frontend and merchandising teams standardizing product presentation blocks.
Critical: Product card definitions are site-scoped and managed under /api/v1/product-card-definitions/* endpoints.
Who This Page Is For
Use this page when you need to build, template, preview, and govern card layouts used in recommendation and product display contexts.
Quick Start (2-5 Minutes)
List templates and fields
Inspect available starter templates and product field metadata.
GET /api/v1/product-card-definitions/templates
GET /api/v1/product-card-definitions/product-fieldsCreate definition
Create site-specific product card definition from scratch.
POST /api/v1/product-card-definitions/site/:siteIdCreate from template
Bootstrap from predefined layout and give it a custom name.
POST /api/v1/product-card-definitions/site/:siteId/from-template/:templateIdPreview with product payload
Generate preview output before assigning to live widgets.
POST /api/v1/product-card-definitions/:id/site/:siteId/previewDuplicate and evolve
Clone definitions for A/B or regional variants.
POST /api/v1/product-card-definitions/:id/site/:siteId/duplicateProduct card endpoints
GET /api/v1/product-card-definitions/templates
GET /api/v1/product-card-definitions/product-fields
GET /api/v1/product-card-definitions/site/:siteId
GET /api/v1/product-card-definitions/:id/site/:siteId
POST /api/v1/product-card-definitions/site/:siteId
POST /api/v1/product-card-definitions/site/:siteId/from-template/:templateId
PUT /api/v1/product-card-definitions/:id/site/:siteId
POST /api/v1/product-card-definitions/:id/site/:siteId/duplicate
POST /api/v1/product-card-definitions/:id/site/:siteId/preview
DELETE /api/v1/product-card-definitions/:id/site/:siteIdRequired Fields / Minimum Payload
| Field | Required | Type | Used by events | Description |
|---|---|---|---|---|
siteId | Required | uuid | All site-scoped product card routes | Site ownership boundary. |
name | Required | string | Create/update/from-template | Definition name shown in selection UIs. |
product card config payload | Required | object | Create/update definition | Layout, field mapping, style, and behavior configuration. |
product (preview payload) | Optional | object | Preview endpoint | Sample product payload for preview rendering. |
Event or Endpoint Decision Matrix
| Scenario | Use This | Why |
|---|---|---|
| Need quick start card layout | templates + from-template endpoint | Fast bootstrap from curated presets. |
| Need fully custom card | POST /product-card-definitions/site/:siteId | Custom design and mapping control. |
| Need safe variant testing | duplicate endpoint | Clone baseline without risking production config. |
| Need pre-release visual validation | preview endpoint | Render preview before attachment to live placements. |
| Need cleanup of deprecated card | DELETE endpoint | Removes obsolete definition cleanly. |
Common Errors and Fixes
Preview fails with missing fields
Cause: Preview product payload missing required mapped fields.
Fix: Use product-fields metadata and provide complete sample payload.
Card appears inconsistent across widgets
Cause: Multiple divergent definitions assigned inconsistently.
Fix: Standardize definition assignment policy per placement type.
Template create fails
Cause: templateId invalid for selected site context.
Fix: Fetch templates first and use exact template ID.
Changes unexpectedly impact live experiences
Cause: Direct update of production definition without duplication.
Fix: Duplicate first, test, then switch assignment deliberately.
Production Checklist
- Product card definitions have versioning and ownership metadata.Required
- Preview is required before production assignment changes.Required
- Templates are used for consistency where applicable.Required
- Definition duplication is preferred for risky changes.Required
- Deprecated cards are cleaned up to reduce drift.Required