Repository navigation
Automate Premium A+ Content and Brand Story at Scale with SP-API π¬ποΈπ #578
Replies: 1 comment 2 replies
|
Thank you for taking the time to write and share this post, and for the sample solution. We really appreciate it. After reading the post, we still have a few questions we hope you can help us with:
Thanks again for sharing this! |
Uh oh!
There was an error while loading. Please reload this page.
If you manage A+ Content for many ASINs, several marketplaces or more than one brand, you know the cost of doing it by hand: the same modules rebuilt per locale, the same images re-uploaded or the same submission rejected. The A+ Content API now covers Premium A+ and Brand Story, including video through the Media API. This post walks through what changed, how a document travels from asset upload to the live detail page, and the practices that make the automation hold up at scale.
Authored by: Jawher A. (@jawheral), Solutions Architect, Selling Partner Developer Services
Why A+ Matters π‘
What Changed in the API π
The latest update to the A+ Content Management API v2020-11-01 keeps the operations you already use for Standard A+ and adds 19 Premium modules and 5 Brand Story modules, plus a Media API for the video assets Premium video modules require.
contentTypeEBC(seller) /EMC(vendor)EBC/EMCBrandStory(both)contentModuleTypeprefixSTANDARD_*(15)PREMIUM_*(19)BRAND_STORY_*(5)Important
A content document must be entirely Standard, entirely Premium or entirely Brand Story. Mixing
STANDARD_*andPREMIUM_*modules in onecontentModuleListis rejected. Standard and Premium documents are limited to seven modules. Premium and Brand Story are designed to be used together, but as two documents.The module inventory
PREMIUM_TEXT(up to 5,000 characters, rich text decorators)PREMIUM_IMAGE_TEXT,PREMIUM_DUAL_IMAGE_TEXT,PREMIUM_FOUR_COLUMN_IMAGES,PREMIUM_FULL_BACKGROUND_IMAGE,PREMIUM_FULL_BACKGROUND_TEXTPREMIUM_IMAGE_CAROUSEL,PREMIUM_NAVIGATION_CAROUSEL,PREMIUM_REGIMEN_CAROUSELPREMIUM_THREE_COLUMN_COMPARISON,PREMIUM_COMPARISON_CAROUSEL,PREMIUM_COMPARISON_SCROLLER(with live price, reviews and Add-to-Cart toggles)PREMIUM_HOTSPOT_IMAGE,PREMIUM_HOTSPOT_IMAGE_TEXTPREMIUM_FAQ,PREMIUM_TECH_SPECSPREMIUM_VIDEO_TEXT,PREMIUM_HERO_VIDEO,PREMIUM_VIDEO_IMAGE_CAROUSELBRAND_STORY_IMAGE_WITH_LOGO(required hero card),BRAND_STORY_ABOUT,BRAND_STORY_FOUR_ASIN,BRAND_STORY_MEDIA_ASSET,BRAND_STORY_QUESTIONSThe Publishing Flow, End to End π§
Step 1: Upload the files. One
createUploadDestinationForResourcecall per file withresource = aplus/2020-11-01/contentDocuments, then POST the binary to the pre-signed URL. Images go straight into the modules'ImageComponent.uploadDestinationId. Video files and their thumbnails go to the Media API first.Step 2: Create media (video modules only).
createMediawithmediaType: VIDEOand aVIDEO_PAIRINGto the thumbnail. The response is the unifiedMediaobject: its top-levelmediaIdis the video andrelatedMedia[0].media.mediaIdis the paired thumbnail; those are thevideoMediaIdandimageMediaIdaVideoComponentneeds. Processing is asynchronous and can take hours, but you do not have to wait for it: create and submit the document as soon as you have the media ids, and Amazon handles the retries while the video is still processing. PollgetMediano more than once per hour per media to follow it. A video that fails processing rejects the whole document.Step 3: Create the document.
createContentDocumentreturns thecontentReferenceKey. Structural errors surface here, field by field. The dry run in front of it,validateContentDocumentAsinRelations, is optional but cheap (see best practice 1).Step 4: Apply ASINs.
postContentDocumentAsinRelationswith the full ASIN set.Note
Keep in mind: the ASIN relation is a replacement, not an append. Whatever you send is the set: ASINs you omit have the content suspended, ASINs you add join the new draft. Changing the ASIN set of an
APPROVEDdocument resets it toDRAFTuntil you resubmit and it is re-approved, so batch ASIN changes and resubmit in the same job. Posting the identical set is a no-op, so diff before you post. Before you touch a live ASIN, ask what is there withsearchContentPublishRecords?asin=; it returnslocaleasen_USwhile every other operation usesen-US, so normalize before comparing.Step 5: Submit and poll.
postContentDocumentApprovalSubmission, thengetContentDocument?includedDataSet=METADATAno more than once per hour:DRAFT β SUBMITTED β APPROVED | REJECTED. Ownership and brand eligibility are checked at submission, not at validation: a403 Unauthorized(Failed asin permissions check, returned as twoerrors[]entries) after a clean validation is expected behavior.listContentDocumentAsinRelations?includedDataSet=METADATAshows theBRAND_NOT_ELIGIBLEbadge on the ASINs to drop.EveryβΆοΈ Try It box in this post links to a use case in the A+ Content Workflows folder of the E. Product and Listings Management collection. Fork the collection once and fill in the environment with your credentials and marketplace.
Five Best Practices π οΈ
1. Validate in two layers π§ͺ
Layer one: the OpenAPI model, on your side. The A+ Content Management API model is the source of truth for the shape of every module: the wrapper key it takes inside a content module, its required fields, its enums and its list bounds. Validate each document against it locally, with a generated SDK client or any JSON Schema validator, before calling the API. It catches every structural
400early (an unexpected property, a missing required field, an enum value out of range) and it can drive your UI editor's forms. The API enforces these same model constraints at its border on every operation, the dry run included, so a document that violates the model never reaches the business validations.Layer two: the dry run, on SP-API's side. The model does not carry the per-module limits, so the second layer is
validateContentDocumentAsinRelations: it runs the full validation without persisting anything and returns every failing constraint at once. Here aPREMIUM_IMAGE_TEXTimage below the module's minimum comes back as two entries in one response:{ "errors": [ { "code": "InvalidInput", "message": "The request is not valid, please check the inputs and try again.", "details": "Request failed validation: validateContentDocumentAsinRelations.postContentDocumentRequest.contentDocument.contentModuleList[0].premiumImageText.image.imageCropSpecification.size.height.value: must be greater than or equal to 600" }, { "code": "InvalidInput", "message": "The request is not valid, please check the inputs and try again.", "details": "Request failed validation: validateContentDocumentAsinRelations.postContentDocumentRequest.contentDocument.contentModuleList[0].premiumImageText.image.imageCropSpecification.size.width.value: must be greater than or equal to 800" } ] }Three rules the model does not carry, so only the service catches them:
PREMIUM_IMAGE_TEXT.bodyText: 1 to 5 items, 500 characters in total). Count the sum, not each line.createContentDocumentreturns the line count and the total as well, so you see them on create, not only on the dry run.desktopImage1464 Γ 600 andmobileImage600 Γ 450 for most full-width modules; 800 Γ 600 forPREMIUM_IMAGE_TEXT; 166 Γ 182 forBRAND_STORY_FOUR_ASINproduct images. Crop withimageCropSpecification, do not resize on your side.Note
A
200from the validator means Amazon ran the validation, not that you passed. Passing is emptyerrors: []andwarnings: []arrays. ASIN problems come back asASIN_FAILED_VALIDATIONwarnings in a200response.2. Design for asset reuse β»οΈ
Every image you upload gets an
uploadDestinationId, every video amediaId, and a document is just a set of modules pointing at those identifiers. Nothing in the API ties an identifier to one document, so the integrations that scale treat assets as a catalog of their own and documents as views on it:sha256(file), the marketplace, the rendition (width Γ height) and theuploadDestinationIdit received. For videos, themediaIdand the ids of its paired thumbnails. Before any upload, look the hash up. The same hero photo referenced from ten locale variants and three Premium documents is one upload, not thirty.uploadDestinationIdholds, and reuse it wherever the same slot appears.This is also what makes the rest of the workflow cheap: a localization job or an ASIN rollout becomes a document write that references existing identifiers.
3. Premium and Brand Story together, localized once π
Premium tells the product story in the A+ slot ("Product description" on a seller's page, "From the manufacturer" on a vendor's). Brand Story tells the brand story under "From the brand" and applies to the whole catalog. The recommended rollout for a brand:
Add a language variation by calling
createContentDocumentagain with the translated modules and the same ASINs. Some locales are auto-generated by Amazon and will not show insearchContentDocuments, so treat a missing locale as "not yet authored", not as an error.searchContentDocumentstells you the tier of every document you own throughbadgeSet:["PREMIUM"],["STANDARD"]or[]for Brand Story. Use it to audit which ASINs still run Standard content and are candidates for an upgrade.4. Build the ASIN β A+ index once, then keep it warm ποΈ
Every A+ integration ends up answering the same two questions: which of my ASINs carry A+ content (and which tier)? and which ASINs does this document cover? The API answers them from two directions, and neither direction is a single call:
searchContentDocuments, thenlistContentDocumentAsinRelationsper documentname,status,badgeSet,updateTime) for every document, then the ASIN set with per-ASIN badgessearchContentPublishRecords?asin=searchContentDocumentsdoes not carry ASINs, and neither relations nor publish records accept a batch, so an integration that refreshes "everything" every time will spend its whole rate budget re-reading data that did not change. The pattern that scales:searchContentDocuments(pageToken), then fan outlistContentDocumentAsinRelations?includedDataSet=METADATAat the operation's rate. A catalog with 2,000 documents costs about 2,000 calls, a couple of minutes at the documented rate, and you do it once per marketplace. Persist the result:contentReferenceKey β {metadata, asinSet with badges}and the invertedasin β [contentReferenceKey].postContentDocumentAsinRelationsor submit for approval, update the index from the request you just sent and the response you just received.updateTime, not by re-fetching. Changes made outside your integration (Seller Central, another tool, an Amazon-side approval) move the document'supdateTimeinsearchContentDocuments. On a schedule, page through the metadata (cheap, no per-document call) and re-fetch relations only for documents whoseupdateTimemoved or that are new. That turns a full fan-out into a delta of a handful of calls.getContentDocument?includedDataSet=CONTENTS) only when a user opens it. Bodies are large, rarely needed for a list view, and cache well: key them bycontentReferenceKey+updateTime.searchContentPublishRecordsis the right call when a user opens a single ASIN or before you touch a live one. Looping it over every listing is the most expensive way to build the index.Tip
Ask a narrower question when you can: "is this document applied to these three ASINs?" ->
listContentDocumentAsinRelationsaccepts anasinSetfilter, so it is one small call instead of paging through the whole relation list.Rate limits and throttling. Rate limits are set per operation, from 5 to 20 requests per second, with a per-developer aggregate of 30 (A+ Content API Rate Limits). The Media operations have their own: getMedia 10, createMedia and updateMedia 5. These limits apply to your application as a whole, not per selling partner. If you serve several selling partners, they share one bucket. Follow the guidance on usage plans and rate limits in the documentation.
A constraint that actually shapes your integration design is the polling guidance for
getContentDocumentandgetMedia: no more than once per hour per document/media while a document isSUBMITTEDor a video is still processing. Tip: PersistcontentReferenceKeywith anextCheckAttimestamp and drive polling from a scheduler.5. Let AI draft, let people approve π€
A+ content is text, images and video produced at scale for many products and locales, which is exactly where generative AI earns its keep. Three places it fits naturally into the flow above, with the guardrail that keeps it safe:
PREMIUM_IMAGE_TEXT: headline 80 characters, body text 500 in total, and so on), keep every non-text field identical, and run the dry run on the result. The validator catches the overruns a model will occasionally produce.Important
Keep a person in the loop before
postContentDocumentApprovalSubmission. Generated copy and imagery are subject to the same A+ content guidelines as anything authored by hand (see the A+ Content API use case guide), claims must be accurate for the product, and you remain responsible for the rights to the media you publish. Treat the model as the drafter and the dry run plus a human review as the approval gate. Make sure to stay compliant with the respective Amazon policies for AI-generated content and the AUP/DUP for solution providers.Get the Sample Solution π₯οΈ
To see the whole flow working, the A+ Content Manager sample solution is a small React and Node.js application that walks it end to end: it lists your ASINs with their A+ state, shows what is published on a product slot by slot, edits or creates Standard, Premium and Brand Story documents from the full module catalog, checks them with the dry run, uploads images, applies ASINs and submits, and previews the result on a simulated desktop detail page. It runs without credentials in a mock mode or against the live API with your LWA credentials.
Conclusion π
Until now the richest content on the detail page was also the most manual. With Premium A+ and Brand Story in the A+ Content Management API and video in the Media API, that content becomes something your systems produce: authored once, localized for every marketplace, applied to every variation ASIN, and kept in step with your catalog. The integrations that get there without friction are not the most elaborate ones, they are the ones that treat validation, asset management and the ASIN-to-content index as first-class parts of the design rather than afterthoughts.
Related resources
Let us know what do you think! π React or reply down below to share your feedback.
Keywords: #amazon-sp-api #aplus-content #premium-aplus #brand-story #media-api #listings #content-management #video #best-practices
Please note the publication date above. While we strive to keep our content current, the rapid evolution of this topic means some details may have changed since publication. For the most up-to-date information, we encourage readers to follow the announcements in SP-API developer documentation.

1 vote ·
All reactions