Amazon Developer

Console

as

Settings
Sign out
Notifications
Alexa
Amazon Appstore
Ring
AWS
Documentation
Support
Contact Us
My Cases

Console

as

Docs
Resources
Ecommerce Plug-ins
Publish
Connect

Sample Store - App Entry with Checkout Service

Disclaimer: This document contains sample content for illustrative purposes only. Organizations should follow their own established best practices, security requirements, and compliance standards to ensure solutions are production-ready.

Overview

This page provides a consolidated view of all the capabilities, APIs, and documentation required to implement a Just Walk Out store using app-based entry where Amazon manages the full payment lifecycle. The retailer manages shopper identity verification through a mobile app, calculates pricing via the Create Purchases API, and submits the priced cart to Amazon via the Checkout Service API. Amazon validates the cart, charges the shopper's payment instrument, and generates the receipt.

Store Profile

Attribute Value
Entry Method Mobile app QR code scan / Credit card tap
Identity Verification Retailer-managed via Verify Identity Keys API (app) / Amazon-managed (credit card)
Charge Calculation Order Delegation via Create Purchases API
Payment Processing Amazon-managed via Checkout Service API (credit card) / Retailer-managed (app)
Receipts Amazon-managed (credit card) / Retailer-managed (app)
Catalog Management Catalog API

APIs in Scope

API Endpoint Purpose
Upload Catalog POST /v1/catalog/upload Upload product catalog to Amazon systems
Get Catalog Upload Status POST /v1/catalog/getCatalogUploadStatus Check catalog upload processing status
Verify Identity Keys POST /v1/identity/identity-keys Authorize shoppers at the JWO gate
Create Purchases POST /v1/order/purchases Receive the shopping cart and calculate pricing (Order Delegation)
Checkout Cart POST /v1/checkout/carts Submit priced cart to Amazon for payment and receipt generation

Required Configurations

The following configurations must be completed in the Merchant Portal and AWS before the store can operate:

Configuration Owner Description
AWS Account Allowlisting (Catalog API) Amazon / Retailer Retailer's AWS account must be allowlisted to invoke the Catalog API
Merchant Portal — Catalog API Amazon Catalog API configured for the merchant in the Merchant Portal
SNS Subscription (Catalog Notifications) Retailer SQS queue subscribed to Amazon's SNS topic for catalog upload results
Identity Connector — ARN Allowlisting Retailer Identity Gateway ARNs allowlisted in the retailer's Identity Connector
Merchant Portal — Identity Connector Amazon Identity Connector configured and associated with store(s)
Identity Connector — Connectivity Test Retailer Connectivity test completed via Merchant Portal
Ordering Connector — ARN Allowlisting Retailer Ordering Gateway ARNs allowlisted in the retailer's Ordering Connector
Merchant Portal — Ordering Connector Amazon Ordering Connector configured and associated with store(s)
Ordering Connector — Connectivity Test Retailer Connectivity test completed via Merchant Portal
Checkout Service — API Access Amazon / Retailer Retailer's AWS account allowlisted to invoke Checkout Cart API
Mobile App — QR Code Generation Retailer Mobile app generates Scan Key Codes per JWO specifications

Available Partners

The following partners have pre-built integrations that support the APIs required for this store model (Catalog, Identity Connector, Ordering Connector, and Checkout Integration):

Partner Catalog Identity Connector Ordering Connector Checkout Integration
Tapin2 Yes Yes Yes Yes

Partners with full API coverage can use the App Entry + Checkout Service Validation Plan to validate their integration for new store deployments without re-testing the full build.

The following partners support individual integrations and can be combined to cover all required APIs:

Partner Available Integrations
Compass Digital Catalog, Identity Connector, Ordering Connector
Grubhub Catalog, Identity Connector, Ordering Connector
Sodexo Everyday Catalog, Identity Connector, Ordering Connector
Transact Campus Catalog, Identity Connector, Ordering Connector
SkyTab Venue Catalog, Identity Connector, Ordering Connector
Cognizant Technology Solutions Catalog, Ordering Connector, Checkout Integration
MyVenue Catalog, Ordering Connector, Checkout Integration
retailcloud Catalog, Ordering Connector, Checkout Integration
CBORD Identity Connector, Ordering Connector
Transact Quickcharge Identity Connector, Ordering Connector
Volante Systems Identity Connector, Ordering Connector
Everi Identity Connector
Lava.ai Identity Connector
YinzCam, Inc. Identity Connector
RapidRMS Catalog

1. Catalog Management

Before your store can operate, you must upload a product catalog to Amazon's systems. The catalog maps SKUs to barcodes, product names, and store IDs so that items picked up by shoppers can be identified.

Key Documentation

Topic Link
Catalog Overview Catalog Considerations
Catalog Data Fields Catalog Items
Reference Architecture Catalog Reference Architecture
API Setup Configure Catalog API
Upload Catalog API Upload Catalog
Get Upload Status API Get Catalog Upload Status
Catalog Maintenance Catalog Maintenance

Catalog Integration Summary

  1. Set up your AWS account and IAM role with Invoke API permissions
  2. Deploy the CloudFormation templates for SQS and connectivity testing
  3. Onboard your AWS account and SQS ARN via the Merchant Portal
  4. Confirm the SNS subscription for upload result notifications
  5. Upload your catalog (max 10,000 items per request, 10 requests/second)
  6. Track upload status via the Get Catalog Upload Status API or SNS/SQS notifications
  7. Download and process the upload result report from the S3 presigned URL (valid for 60 minutes)

2. Shopper Entry — App-Based Authorization

Shoppers enter the store by scanning a QR code generated by your mobile app. Amazon calls your Verify Identity Keys API to authorize the shopper. You verify the identity key and return a gate decision.

Key Documentation

Topic Link
Entry Experience Overview Shopper Entry Experience
Mobile App Entry Mobile App Entry
API Setup Configure Shopper Entry API
Verify Identity Keys API VerifyIdentityKeys

Integration Summary

  1. Build a mobile app that generates QR code Scan Key Codes per JWO specifications
  2. Implement the Verify Identity Keys API (POST /v1/identity/identity-keys) as your Identity Connector
  3. Decode the Base64-encoded identityKey and validate the shopper
  4. Return visitor details with type SHOPPER, ASSOCIATE, or CASH_SHOPPER
  5. Handle all requests idempotently using the authEvent.id
  6. Ensure responses return within 2 seconds

Gate Behavior

Response Code Gate Action
200 Gate opens
400 Gate remains closed
401 Gate remains closed
429 Gate remains closed
500 Gate follows store default decision

3. Charge Calculation — Ordering Connector

After the shopper exits, Amazon calls your Create Purchases API with the virtual shopping cart. You calculate pricing, apply promotions and taxes, and return a purchaseId. This is the Order Delegation model where the retailer owns charge calculation.

Key Documentation

Topic Link
Charge Calculation Overview Charge Calculation Overview
Setup Charge Calculation Setup
API Setup Configure Charge Calculation API
Create Purchases API Create Purchases
CloudFormation Templates Ordering Connector CloudFormation Templates

How It Works

  1. Shopper exits the store
  2. Amazon sends the virtual cart to the retailer via POST /v1/order/purchases
  3. Retailer calculates pricing, promotions, and taxes using their POS system
  4. Retailer returns a purchaseId for cross-system tracking
  5. Empty carts return an empty purchaseId and trigger pre-auth cancellation

4. Checkout — Submit Cart to Amazon

After calculating pricing, the retailer submits the priced cart to Amazon via the Checkout Service API. Amazon validates the cart data (line items, totals, promotions, taxes), charges the shopper's payment instrument, and generates the receipt.

Key Documentation

Topic Link
Checkout Service Overview Checkout Service

How It Works

Step Action
1 Retailer receives cart via Create Purchases API
2 Retailer calculates pricing, promotions, and taxes
3 Retailer calls POST /v1/checkout/carts with the priced cart
4 Amazon validates line items match the original cart
5 Amazon validates order totals (priceTotal = subTotal - promotionsTotal + salesTaxTotal)
6 Amazon charges the shopper's payment instrument
7 Amazon returns orderId on success (201)

Validation Rules

Amazon validates the checkout payload before processing payment:

Validation Description
Cart content match lineItems must match the cart Amazon sent to the Ordering Connector
Price calculation totalPrice = price - promotions + salesTax for each line item
Order totals priceTotal = subTotal - promotionsTotal + salesTaxTotal
Decimal precision All amounts must be rounded to 2 decimal places
Non-empty cart lineItems array must not be empty
Item pricing Every line item must have a price

Empty Cart Handling

When the shopper exits without taking items, Amazon sends an empty cart to the retailer's Create Purchases API. The retailer returns a valid purchaseId. The retailer does not need to call the Checkout API or cancel the pre-auth — Amazon cancels the pre-auth automatically.

5. Testing

Test Plans

Test Plan Link
Catalog Test Plan Catalog Test Plan
App Entry Store Test Plan App Entry Store Test Plan
Checkout Service Store Test Plan Checkout Service Test Plan

Validation Plan (Existing Partners)

For existing partners who have pre-built integrations and need to validate their integration for a new store deployment without re-testing the full build:

Validation Plan Link
App Entry + Checkout Service Validation Plan App Entry + Checkout Service Validation Plan

Test Cases

Test Cases Link
Catalog Upload Catalog Upload Test Cases
Verify Identity Keys Verify Identity Keys Test Cases
Create Purchases Create Purchases Test Cases
Checkout Service Checkout Service Test Cases
Cart Payload Validation Cart Payload Validation Test Cases

Testing Phases

Phase Description Link
Functional / Mock Testing Test APIs with mock data before connecting to live systems Mock Testing
Connectivity Testing Verify your AWS account can invoke Amazon APIs Connectivity Testing
End-to-End Testing Complete shopping journey from entry to checkout E2E Testing
Load Testing Validate performance under peak concurrent load Load Testing

6. Operational Readiness

Resource Link
Operational Readiness Overview Overview
Well-Architected Review App Entry + Checkout Service Well-Architected

End-to-End Flow

┌─────────────────────────────────────────────────────────────────┐
│                    PRE-LAUNCH SETUP                              │
│                                                                  │
│  1. Upload Catalog ──► POST /v1/catalog/upload                  │
│  2. Check Status ────► POST /v1/catalog/getCatalogUploadStatus  │
│  3. Process SNS/SQS notification ──► Download result report     │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    SHOPPER ENTRY                                 │
│                                                                  │
│  1. Shopper opens mobile app ──► QR code generated              │
│  2. Shopper scans QR at gate                                    │
│  3. Amazon calls ──► POST /v1/identity/identity-keys            │
│  4. Retailer verifies identity key ──► 200 = gate opens         │
│  5. Pre-auth placed on payment instrument                       │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    SHOPPING                                       │
│                                                                  │
│  Shopper picks up items ──► Amazon tracks virtual cart           │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    SHOPPER EXIT & CHECKOUT                        │
│                                                                  │
│  1. Shopper exits store                                         │
│  2. Amazon calls ──► POST /v1/order/purchases                   │
│  3. Retailer calculates pricing, promotions, taxes              │
│  4. Retailer returns purchaseId                                 │
│  5. Retailer calls ──► POST /v1/checkout/carts (priced cart)    │
│  6. Amazon validates cart and charges payment instrument         │
│  7. Amazon generates and delivers receipt                       │
│  8. Empty cart ──► Amazon cancels pre-auth automatically        │
└─────────────────────────────────────────────────────────────────┘
Follow us:
amazon_developer_logo

© 2010-2026, Amazon.com, Inc. or its affiliates. All Rights Reserved.

Terms

Amazon Developer Blog

Contact Us