Reference Architecture

Prerequisites
Catalog API Solution Overview
Prepare your catalog
Setup your environment
Developing the integration

Prerequisites

In order for a catalog to be set up, the following must already exist:

The Store(s) for which the catalog is being set up.
Store login credentials which include a user with catalog upload permissions.
Completed the Tax Interview and State tax registration process, if applicable.

Catalog API Solution Overview

The Catalog API provides a programmatic way to insert and update existing catalog items. The data flow design is a representative sample of the business workflows typically used in the retail space.

Prepare your catalog

Define the process to update the catalog in the Amazon systems. It is recommended to look into how frequent your catalog changes. The frequency will inform the architecture decision and data flow for the catalog updates. For detailed description, review Catalog Considerations.
Identity the catalog data store. You will need to have access to the catalog updates. This might require to work with the security team to ensure access is granted and the catalog data is secured.
The Amazon Catalog API provides you with a set of required fields to upload a catalog. The values might be named differently in your catalog system. You are required to ensure that the correct data elements are mapped between you catalog and the Amazon Catalog API.

Setup your environment

AWS Account: This pattern requires an AWS account. For instructions on how to get an AWS account, please see here
Completed the Amazon onboarding: Retailer onboarding must be completed before the implementation of this solution
AWS Service onboarding: you will be working with the Amazon team to onboard your Catalog API to the Amazon systems. The process will include steps such as providing an IAM role ARN that will be used to call the Amazon API. The Amazon team will provide API invocation endpoints based on the AWS region and the Amazon product you are utilizing for your store. If you elect to use the solution in the Target Architecture section, you will also be required to provide an AWS SQS ARN and follow steps to confirm subscription to the SQS service. For steps on how to confirm SQS subscriptions, please see AWS docs here.

Developing the integration

The following reference architecture is provided as a guide for implementing the catalog API. For detailed step by step instructions, visit the Amazon Just Walk Out Merchant Portal

This sample solution follows the following steps:

Catalog upload status in this sample solution is provided through an Amazon SNS topic. For an example of Catalog upload status check using API, see full solution guide in the Amazon Merchant Portal.

Customer will start the process by calling an AWS Lambda function to start the catalog upload.

Note: You are allowed to perform 10 requests per second and max of 10,000 items per upload.
The Lambda function will acquire AWS STS credentials from an AWS IAM Role to authorize the operations to manage the catalog upload process.

Note: Please follow your organization's best practices for least privilege permissions to the IAM Role while will providing the necessary authorization to perform the operations required to manage the process to upload the catalog. Please ensure the IAM Role has the Invoke API Policy. Sample policy provided in the AWS Documenation. Failure to attach the correct permissions to the IAM Role will result in a HTTP 403 error when calling the Catalog API
A Lambda function will trigger and manage the catalog upload process. AWS Step Functions will perform three key operations shown in the diagram.
The Step Functions downloads the JSON input file from an Amazon S3 bucket.
The next steps will read the catalog file and perform validation to ensure the catalog has no errors or missing data required by the API.

Note: This will prevent any errors while loading the catalog early in the process. Once the validation is completed, the lambda function will return to the Step Functions to progress on the catalog upload process.
The Step Functions will call a Lambda function to record the catalog upload request to track the process. This will allow you to record all catalog upload requests.
The Lambda function will record the catalog upload request to an Amazon DynamoDB table.
Once the data recording is complete, the Lambda function will return to the Step Functions. The Step Functions will trigger a Lambda function to begin the process of invoking the JWO Catalog API.
The Lambda function will acquire STS credentials from the AWS IAM Role to authorize the operations to upload the catalog upload to JWO.
The Lambda function will record the upload attempt to a DynamoDB table. This will enable tracking each catalog upload process.

Note: The IAM Role must be allowlisted in JWO to authorize the calls to the JWO APIs. Failure to allowlist the IAM Role will result in a HTTP 403 error when calling the Catalog API.
The Lambda function will call the Catalog API and pass the payload. For detailed instructions on authenticating and calling the Catalog API, please see full solution. Amazon API will perform validation logic on the incoming request and respond with an ingestion ID or an error message if validation fails.

Note: The ingestion ID is used later on to look up and match incoming messages. You are responsible for storing the ingestion ID after receive the API response from Amazon. For more details on the JSON message response, please consult the API specification. Amazon will perform a search for each item based on the SKU. If an item matches then it will update the stored values using the values passed by the API. If no match is found, then a new item is created.
The Lambda function will receive and process the response from the Catalog API.
The Lambda function will update the DynamoDB table with the status of the upload.

Note: If the API call returned an error, then there are no more events. If the API call returns an Ingestion ID, then the process continues.
Once the processing concludes, JWO will publish a message to an Amazon SNS topic managed by JWO.
The SNS topic will publish the message payload to an Amazon SQS queue in your AWS account.

Note: Please ensure that you have completed the steps to subscribe to the SNS topic. It is recommended to setup an extra notification on the SQS queue, such as email. The customer is responsible for setting up notification on the SQS queue to be notified when JWO publishes a message.
Once a new message is received by the SQS queue, SQS will invoke a lambda function to process the incoming message. The Lambda function will extract the message element from the JSON, which contains a URL for the JSON response from JWO for the ingestion job.
The Lambda function will acquire STS credentials from the AWS IAM Role to process the catalog upload response starting with the analysis of the SQS queue message.
The lambda function will download the result JSON from the S3 presigned URL, which contains the item results and stop. The link will be valid for 60 minutes before expiring.
The lambda function will call the S3 presigned URL, open up the JSON, and store the result in the S3 bucket.
The Lambda function will update DynamoDB with the SQS queue message, specifically the S3 presigned URL for upload results.

The customer will process the results of the catalog upload on their side and perform any follow actions and clean up.