Planning and setup
This section covers the initial steps for a successful catalog integration.Understand your integration timeline
Catalog integration requires careful planning. Allocate two to four weeks for initial setup:- Week 1 – AWS account setup, S3 bucket provisioning, and IAM role configuration.
- Week 2 – Test catalog creation, validation, and initial submission to the staging environment.
- Weeks 3–4 – Error resolution, production launch, and monitoring.
Assign dedicated resources
Catalog integration involves metadata transformation, automation scripting, and ongoing monitoring. Make sure your team can cover the following areas:- Export and transform content metadata into Enhanced Metadata Bridge for Entertainment Resources (EMBER) format.
- Script automation for catalog generation and upload.
- Validate catalogs, test on devices, and monitor ingestion reports.
- Configure AWS CLI, manage credentials, and set up cron jobs.
Start with the staging environment
Always validate in the staging environment before submitting to production and follow these high-level steps:- Submit test catalogs to the staging/ directory.
- Add test devices to the allow list with your Amazon representative.
- Verify that content appears correctly on devices.
- Fix all errors and warnings before production launch.
Upload strategy
How you upload your catalog affects processing speed, risk, and reliability.Use full catalog replace sparingly
To completely rebuild your catalog usetype="CATALOG_FULL" in the manifest file. This approach can remove stale or unreferenced entities but carries higher risk because any missing content is deleted. Schedule full replacements during off-peak hours.
Use incremental updates for regular changes
For daily or weekly updates, usetype="CATALOG_UPDATE" in the manifest file. Incremental updates include only changed entities (new, updated, or deleted), preserve unchanged content, process faster, and carry lower risk.
Understand catalog-level actions
In addition to the manifest-leveltype (CATALOG_FULL and CATALOG_UPDATE), each catalog element has an action attribute that controls how its contents are processed:
upsert(default) – Adds new entities, updates existing entities, and preserves everything else. Use this for incremental updates.replace– Removes all existing entities in the catalog and replaces them with the contents of the submission. Use this with caution, as any entity not included in the file is deleted.
Delete element within an upsert update. When deleting hierarchical content, delete children before parents (episodes before seasons, seasons before series).
For the full reference, including delete versioning behavior and examples, see Delete and catalog actions.
Automate your upload process
Manual uploads are error-prone. Create automated scripts that perform the following steps:- Generate the catalog from your content management system (CMS) database.
- Validate against the XSD automatically.
- Compress files.
- Assume the IAM role and refresh credentials.
- Upload with proper sequencing.
- Schedule through a cron job (daily at 2:00 AM recommended).
Roll back to a known good catalog
If a catalog submission introduces errors, such as missing content, broken relationships, or incorrect metadata, you can revert to a previous known good state by submitting a full replacement with your last validated catalog. To roll back your catalog:- Identify the last validated catalog version in your archive.
- Update the manifest file to use
type="CATALOG_FULL"with a new, higher version number. - Submit the archived catalog files to the S3 path.
- Monitor the ingestion report to confirm the rollback processed without errors.
- Archive every successfully ingested catalog with its timestamp and version number.
- Store archives in a consistent location.
- Validate archived catalogs against the XSD before resubmitting.
- Keep at least three recent good catalogs available for recovery.
Monitoring and maintenance
Regular monitoring helps you catch issues early and keep your catalog healthy.Monitor ingestion reports daily
Subscribe to ingestion report emails and do the following:- Verify the error count equals zero.
- Review warnings and plan fixes.
- Verify item counts match expectations.
- Track skipped items.
Review catalog summary reports weekly
The daily catalog summary report provides a holistic view of your catalog health. Review the following:- All current errors and warnings
- Optimization suggestions
- Content quality metrics
- Week-over-week trends
Maintain upload frequency requirements
Required minimums:- Incremental updates: At least every seven days, or content might be deprioritized.
- Full catalog refresh: At least every 30 days, or the catalog might be suppressed.
- Daily: New releases, availability changes, schedule updates
- Weekly: Metadata corrections, image updates
- Monthly: Full validation and cleanup
File organization
Organizing your catalog files consistently makes submissions easier to manage and debug.Split large catalogs into multiple files
Don’t create monolithic XML files. Instead, split catalogs by type or update frequency:- By catalog type: movies.xml, tv-shows.xml, schedules.xml
- By update frequency: daily-updates.xml, stable-content.xml
Use consistent file naming
Include timestamps in file names for tracking. For example:- catalog-movies-20260425-140000.xml.zst
- catalog-schedules-20260425-140000.xml.zst
- manifest-20260425-140000.manifest
Organize multiple catalogs logically
When you use multiple catalogs of the same type, organize by purpose:- ORIGINAL_CONTENT – Your original productions.
- LICENSED_CONTENT – Third-party licensed content.
- LOCAL_STATIONS – Local broadcast affiliates.
- EXTERNAL_STATIONS – TMS or Gracenote Video Data (GVD) referenced stations.
ID management
Consistent, durable IDs are critical for content tracking and cross-catalog references.Use durable, meaningful IDs
IDs must never change after creation. Choose descriptive, permanent identifiers. Good examples:id="MOVIE_AVENGERS_2024"id="SERIES_FRIENDS"id="NFL_2025_W01_SEA_SF"
id="Movie 123"(contains spaces)id="temp_id"(not durable)id="12345"(not descriptive)
Establish ID conventions
Document your ID patterns before you start building catalogs. Amazon recommends the patterns listed in the following table.Never reuse IDs
When content is removed, retire its ID permanently. Don’t reuse an ID for different content. Create new IDs for remakes or reboots, and maintain an ID registry or database.Version management
Versioning controls how the system handles incremental catalog updates and prevents out-of-order overwrites.Choose a versioning strategy
The following are three common versioning approaches. Sequential (simple)Track versions in your system
Maintain version history for each entity:- Store the current version for each entity in your database.
- Increment the version before each update.
- Never submit a version less than or equal to the current version.
Content metadata
This section covers recommended practices for the metadata fields that have the greatest impact on content matching and the customer experience.Titles and descriptions
Provide territory-specific title variations when content has different titles in different regions.Descriptions(50–200 characters): Concise, enticing summary.Synopses(200–500 characters): Detailed plot without spoilers.- Use proper grammar and spelling.
- Avoid marketing hyperbole.
- Don’t spoil major plot twists.
Images
Use high-quality images that meet the following requirements:- Minimum resolution: HD (1920x1080).
- Recommended: 4K (3840x2160) for future-proofing.
- Maximum file size: 10 MB.
- Professional quality with no watermarks or artifacts.
- Use public HTTPS URLs.
- Valid SSL certificates are required.
- No authentication or headers required.
- Test that URLs return HTTP 200.
- Images must be available 24/7.
External IDs
External IDs are the primary matching mechanism. Include all available external IDs.- Appear as a duplicate instead of merging with existing entries.
- Have lower search ranking.
- Miss cross-service recommendations.
Genres and keywords
Use EMBER genre schemes when possible.TV content hierarchy
TV content requires a specific creation order to maintain valid relationships between series, seasons, and episodes.Create entities in the correct order
Always create TV content in this order:TVSeries, then TVSeason, then TVEpisode.
Include both episode relationships
For eachTVEpisode, include both isEpisodeOfSeason and isEpisodeOfSeries. This provides flexible navigation and supports both series-level and season-level browsing.
Ratings and content appropriateness
Content ratings help customers make informed viewing decisions. Provide territory-specific ratings for each region where your content is available.Provide territory-specific ratings
Include the appropriate rating system and certification for each territory.Use descriptors for transparency
Help parents make informed decisions by including reason codes (V for violence, L for language, S for sexual content), clear descriptor text, and official rating board language.
Live events and scheduling
Live events can be represented in two ways depending on your distribution model.Use ProgramAiringOffers for app-based live streaming
UseProgramAiringOffers when the event streams live in your app only. In this model, users access the event through your app (not a broadcast channel), and the Airing element has no stationRef attribute.
Examples include an NFL game exclusive to your app, a concert livestream exclusive to your service, a pay-per-view boxing match, an esports tournament, or a theater performance on your streaming service.
Use ScheduleCatalog for linear broadcast
UseScheduleCatalog when the event broadcasts on a TV station or channel. In this model, the event is available to anyone tuned to that station, the Airing element has a stationRef attribute, and the event appears in the 24-hour broadcast schedule.
Examples include an NFL game on CBS, the Olympics on NBC, or an awards show on ABC.
Use both when applicable
Many partners broadcast the same event on linear TV and in their streaming app. In this case:- Create one
SportsEventprogram. - Reference it in
ScheduleCatalogfor linear broadcast. - Reference it in
ProgramAiringOffersfor app streaming. - Each reference can have different entitlements, blackout rules, and quality levels.
Reuse live events for VOD replay
After a live event concludes, you can offer it on-demand using the same program entity. Submit bothProgramAiringOffers and ProgramOffers in the same catalog update to ensure a seamless transition from live to on-demand.
During the event (time-bound live streaming)
Linear catalogs
If you distribute linear broadcast content (TV stations, Free Ad-Supported Television (FAST) channels), Amazon strongly recommends you useExternalStation references with TMS or Gracenote station IDs.
Use fully-defined Station elements only when you have original content that is not available in external systems, such as local productions or custom FAST channels. When creating a fully-defined station using the Station element, you must include applicable schedules, programs, offers, and policies.
Benefits of using external station references:
- No program metadata required – the external system already has full program details.
- No schedule submission needed – TMS or Gracenote provides schedule data.
- Automatic updates – program and schedule changes are handled by the external provider.
- Reduced maintenance – you only maintain
StationOffers(access and entitlements). - Faster integration – submit station IDs and access rules, not thousands of programs.
ExternalStationelements with TMS or GVD IDs.StationOffers(entitlements, geo-restrictions).
- All program metadata (titles, descriptions, images).
- Complete broadcast schedules (24-hour daily updates).
- Program relationships and series hierarchies.
- Ratings and content advisories.
Related topics
- EMBER Catalog Integration Overview – Overview of the catalog integration process
- EMBER Specification Overview – Schema reference with catalog types, core concepts, and data types
- EMBER Examples – XML examples for common catalog scenarios
- All EMBER Elements – Complete element directory

