Sample Store - App Entry
- Overview
- 1. Catalog Management
- 2. Shopper Entry — App-Based Authorization
- 3. Charge Calculation — Order Delegation
- 4. Testing
- 5. Operational Readiness
- End-to-End Flow
- Generate Project Task Lists
- Operational Readiness Checklist
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. In this model, the retailer manages shopper identity verification through a mobile app, delegates charge calculation to their own POS system, and handles payment orchestration independently.
Store Profile
| Attribute | Value |
|---|---|
| Entry Method | Mobile app QR code scan |
| Identity Verification | Retailer-managed via Verify Identity Keys API |
| Charge Calculation | Order Delegation (retailer POS) |
| Payment Orchestration | Retailer-managed |
| 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 create a purchase record |
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 |
| 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, and Ordering Connector):
| Partner | Catalog | Identity Connector | Ordering Connector |
|---|---|---|---|
| Compass Digital | Yes | Yes | Yes |
| Grubhub | Yes | Yes | Yes |
| Sodexo Everyday | Yes | Yes | Yes |
| Tapin2 | Yes | Yes | Yes |
| Transact Campus | Yes | Yes | Yes |
| SkyTab Venue | Yes | Yes | Yes |
Partners with full API coverage can use the App Entry 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 |
|---|---|
| CBORD | Identity Connector, Ordering Connector |
| Transact Quickcharge | Identity Connector, Ordering Connector |
| Volante Systems | Identity Connector, Ordering Connector |
| Cognizant Technology Solutions | Catalog, Ordering Connector |
| MyVenue | Catalog, 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
- Set up your AWS account and IAM role with Invoke API permissions
- Deploy the CloudFormation templates for SQS and connectivity testing
- Onboard your AWS account and SQS ARN via the Merchant Portal
- Confirm the SNS subscription for upload result notifications
- Upload your catalog (max 10,000 items per request, 10 requests/second)
- Track upload status via the Get Catalog Upload Status API or SNS/SQS notifications
- 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
- Build a mobile app that generates QR code Scan Key Codes per JWO specifications
- Implement the Verify Identity Keys API (
POST /v1/identity/identity-keys) as your Identity Connector - Decode the Base64-encoded identityKey and validate the shopper
- Return visitor details with type SHOPPER, ASSOCIATE, or CASH_SHOPPER
- Handle all requests idempotently using the authEvent.id
- 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 — Order Delegation
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.
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 |
Integration Summary
- Implement the Create Purchases API (
POST /v1/order/purchases) as your Ordering Connector - Receive the cart with item SKUs, quantities, shopping trip details, and auth events
- Calculate pricing, promotions, and taxes using your POS system
- Return a purchaseId for cross-system tracking
- Handle empty carts by returning an empty purchaseId and triggering pre-auth cancellation
- Route unrecognized SKUs to your bad cart handling process
- Handle all requests idempotently using the idempotentShoppingTripId
4. Testing
Test Plans
| Test Plan | Link |
|---|---|
| Catalog Test Plan | Catalog Test Plan |
| App Entry Store Test Plan | App Entry Store 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 Validation Plan | Validation Plan |
Test Cases
| Test Cases | Link |
|---|---|
| Catalog Upload & Inventory Sync | Catalog Upload Test Cases |
| Verify Identity Keys | Verify Identity Keys Test Cases |
| Create Purchases | Create Purchases Test Cases |
| API Gateway Alarm Validation | See API Gateway Alarm Test below |
API Gateway Alarm Test
Objective: Confirm that API Gateway CloudWatch alarms trigger correctly when error thresholds are breached.
| Test Case | Trigger Condition | Expected Alarm Behavior |
|---|---|---|
| 4xx Error Rate Breach | Send repeated invalid requests to exceed the 4xx error rate threshold | CloudWatch alarm transitions to ALARM state; SNS notification delivered to configured subscribers |
| 5xx Error Rate Breach | Simulate backend failures to exceed the 5xx error rate threshold | CloudWatch alarm transitions to ALARM state; SNS notification delivered to configured subscribers |
| Latency Threshold Breach | Send requests that cause response latency to exceed the p99 threshold | CloudWatch alarm transitions to ALARM state; SNS notification delivered to configured subscribers |
| Throttling Alarm | Send requests exceeding the configured rate limit to trigger 429 responses | CloudWatch alarm transitions to ALARM state; SNS notification delivered to configured subscribers |
| Alarm Recovery | Stop sending error-generating traffic after alarm triggers | CloudWatch alarm transitions back to OK state within the configured evaluation period |
Test Steps:
- Identify the CloudWatch alarms configured for your API Gateway (4xx rate, 5xx rate, latency, throttling)
- Note the alarm thresholds and evaluation periods
- Generate traffic that breaches the threshold (e.g., send requests with invalid payloads for 4xx, or trigger backend errors for 5xx)
- Verify the alarm transitions to ALARM state in the CloudWatch console
- Verify the SNS notification is delivered (email, PagerDuty, Slack, or other configured target)
- Stop the error-generating traffic and confirm the alarm returns to OK state
Acceptance Criteria:
- All configured alarms trigger within the expected evaluation period when thresholds are breached
- Notifications are delivered to all configured subscribers
- Alarms recover to OK state when the breach condition is resolved
- No false positives during normal operational traffic
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 charge | E2E Testing |
| Load Testing | Validate performance under peak concurrent load | Load Testing |
5. Operational Readiness
| Resource | Link |
|---|---|
| Operational Readiness Overview | Overview |
| App Entry Store Well-Architected | Well-Architected Review |
| Catalog Upload Well-Architected | Catalog Upload Well-Architected Review |
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 & CHARGE │
│ │
│ 1. Shopper exits store │
│ 2. Amazon calls ──► POST /v1/order/purchases │
│ 3. Retailer calculates pricing, promotions, taxes │
│ 4. Retailer returns purchaseId │
│ 5. Retailer charges payment instrument │
│ 6. Empty cart ──► cancel pre-auth │
└─────────────────────────────────────────────────────────────────┘
Generate Project Task Lists
📋
Download Project Task Lists
Generate comprehensive project task lists with task owners, status tracking, and acceptance test cases for your App Entry JWO store implementation.
Operational Readiness Checklist
✅
Would you like an operational readiness checklist?
Download a checklist covering all operational readiness items for your app-entry JWO store launch.
