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
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
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 — 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
How It Works
- Shopper exits the store
- Amazon sends the virtual cart to the retailer via
POST /v1/order/purchases
- Retailer calculates pricing, promotions, and taxes using their POS system
- Retailer returns a purchaseId for cross-system tracking
- 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
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
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:
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
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 │
└─────────────────────────────────────────────────────────────────┘
