A+ Content API v2020-11-01 Use Case Guide

Use the A+ Content API to create and edit high-quality content to help buyers make purchasing decisions. A+ content consists of collections of modules (known as a content document) that you can use to display product images and text. For an example of a content document, and a complete list of available modules, refer to A+ Content Examples.

Tutorial: Create, edit, and publish A+ content

Learn how to create a new content document, add ASINs to the content document, and get the content document approved for publication.

Prerequisites

To complete this tutorial, you need:

• Authorization from the selling partner for whom you are making calls. For more information, refer to Authorizing Selling Partner API applications.
• The Product Listing role assigned to your developer profile.
• The Product Listing role selected in the app registration page for your application.
• One or more ASINs for which you want to publish content.
• Content that you want to publish.

Step 1. Find out which content documents are published to an ASIN

Call the searchContentPublishRecords operation.

To get the content documents and metadata for the records that are returned, use the getContentDocument operation and pass in the contentReferenceKey value.

Step 2. Get all of the content documents that the selling partner created

Call the searchContentDocuments operation.

To get the content documents for the records that are returned, call the getContentDocument operation and pass in the contentReferenceKey value.

Step 3. Create a content document

To create a content document, complete the following tasks:

1. Construct a JSON content document
2. Create upload destinations for images
3. Upload images
4. Submit the content document for validation
5. Create a content document
6. Add ASINs to the content document

Construct a JSON content document

Content documents are composed of one or more content modules. Content documents for selling partners can contain up to seven modules; content documents for vendors can contain up to five content modules.

ContentDocument definition:

contentDocument example:

{
  "contentDocument": {
    "name": "Example content document",
    "contentType": "EMC",
    "locale": "en-US",
    "contentModuleList": [
      {
        "contentModuleType": "STANDARD_HEADER_IMAGE_TEXT",
        "standardHeaderImageText": {
          "headline": {
            "value": "Lorem ipsum",
            "decoratorSet": []
          },
          "block": {
            "image": {
              "uploadDestinationId": "SampleID",
              "imageCropSpecification": {
                "size": {
                  "width": {
                    "value": 970,
                    "units": "pixels"
                  },
                  "height": {
                    "value": 600,
                    "units": "pixels"
                  }
                },
                "offset": {
                  "x": {
                    "value": 7,
                    "units": "pixels"
                  },
                  "y": {
                    "value": 0,
                    "units": "pixels"
                  }
                }
              },
              "altText": "Lorem ipsum"
            },
            "headline": {
              "value": "Nunc faucibus neque auctor faucibus pretium.",
              "decoratorSet": []
            },
            "body": {
              "textList": [
                {
                  "value": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc faucibus neque auctor faucibus pretium. Quisque sed blandit nunc. Pellentesque malesuada lorem vitae justo efficitur viverra.",
                  "decoratorSet": []
                }
              ]
            }
          }
        }
      }
    ]
  }
}

Create upload destinations for images

Call the createUploadDestinationForResource operation of the Uploads API v2020-11-01.

Save the uploadDestinationId value to include in your content document in Submit the content document for validation. Save the url value for Upload images.

Upload images

Use the following cURL command with the url response element that the previous task returned.

Example cURL command:

{
  "codes": [
    {
      "code": "curl -F \"key=sc/7ae2d3b1-fdd3-42c4-98c4-9cc509fb95d8.png\" \\\n-F \"acl=private\" \\\n-F \"policy=eyJjb25kaXRpb25zIjpbeyJidWNrZXQiOiJhcGx1cy1tZWRpYS1iZXRhIn0seyJrZXkiOiJzb3RhLzdhZTJkM2IxLWZkZDMtNDJjNC05OGM0LTljYzUwOWZiOTVkOC5wbmcifSx7ImFjbCI6InByaXZhdGUifSx7IngtYW16LW1ldGEtb3duZXIiOiJBMkNaMDROR0tZRFhEViJ9LHsieC1hbXotYWxnb3JpdGhtIjoiQVdTNC1ITUFDLVNIQTI1NiJ9LHsieC1hbXotY3JlZGVudGlhbCI6IkFLSUE2TDZSN1FFNTZGNkdNRzVFLzIwMjAxMTE2L3VzLWVhc3QtMS9zMy9hd3M0X3JlcXVlc3QifSx7IngtYW16LWRhdGUiOiIyMDIwMTExNlQxODQ2MjNaIn0sWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsMSwzMTQ1NzI4XV0sImV4cGlyYXRpb24iOiIyMDIwLTExLTE2VDIxOjQ2OjIzLjg2OFoifQ==\" \\\n-F \"x-amz-credential=AKIA6L6R7QE56F6GMG5E/20201116/us-east-1/s3/aws4_request\" \\\n-F \"x-amz-algorithm=AWS4-HMAC-SHA256\" \\\n-F \"x-amz-date=20201203T011128Z\" \\\n-F \"x-amz-signature=c5c8efd95d883b6787a2b1a93c7c066f01cb4e8d7be3ece4360aa800332e0cf9\" \\\n-F \"x-amz-meta-owner=A2CZ04NGKYDXDV\" \\\n-F \"[email protected]\" \\\nhttps://aplus-media.s3.amazonaws.com",
      "language": "curl"
    }
  ]
}

Confirm that you received a 2xx status code in the response. The 2xx status code indicates a successful image file upload.

Submit the content document for validation

Call the validateContentDocumentAsinRelations operation.

📘

Note

If your content document includes images, add the uploadDestinationId value that you received in Create upload destinations for images to your content document.

Check for errors in the response. If you receive an error, correct the error and retry. Repeat until you receive no errors.

📘

Note

A 200 status code in the response indicates that Amazon ran a validation on your content document. This status code does not indicate that your content document passed validation. Your content document passes validation when the validateContentDocumentAsinRelations operation returns no errors.

Create a content document

Call the createContentDocument operation.

Add ASINs to the content document

Call the postContentDocumentAsinRelations operation.

Step 4. Get the content document approved for publication

To submit your content document, call the postContentDocumentApprovalSubmission operation.

Check for warnings and errors in the response. If you receive a warning or error, correct and retry. Repeat until you receive no warnings errors.

To check your submission status, call the getContentDocument operation and check the status property. Possible status values are:

• APPROVED: The content is approved and published to the applied ASINs.
• REJECTED: The content is rejected during review. Revise the content based on the provided rejection reasons and resubmit.
• DRAFT: The content is not yet submitted for approval. Wait a minimum of one hour and resubmit.
• SUBMITTED: The content is submitted for approval and is currently in review. Wait a minimum of one hour and resubmit.

📘

Note

Call the getContentDocument operation no more than once an hour for each content document that you check for approval status.

Tutorial: Manage A+ content

This tutorial demonstrates how to manage existing content.

Prerequisites

To complete this tutorial, you need:

• Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API applications for more information.
• The Product Listing role assigned to your developer profile.
• The Product Listing role selected in the app registration page for your application.
• One or more ASINs to which you would like to publish content.
• Content that you want to publish.

Step 1. Suspend a content document from all applied ASINs

Call the postContentDocumentSuspendSubmission operation.

📘

Note

When you publish a content document to an ASIN that already has content published to it, Amazon suspends the existing content from the ASIN. This suspension also occurs when you remove an ASIN from a content document. You don't need the postContentDocumentSuspendSubmission operation in either scenario.

Step 2. Get published content

To get content that is already published by the selling partner, call the getContentDocument operation. Set includedDataSet equal to METADATA to get content metadata. Set includedDataSet equal to CONTENTS to get content documents.

Step 3. Update a content document

Call the updateContentDocument operation.

Step 4. Get the ASINs that are related to a content document

Call the listContentDocumentAsinRelations operation.

Step 5. Add or remove ASINs from a content document

Call the postContentDocumentAsinRelations operation.

🚧

Important

The ASINs that you post replace all ASINs related to a content document, which can result in additional or removed ASINs. Removing the ASIN can suspend the content document from the ASIN. Post the entire set of ASINs related to a content document.