ShopSavvy Alexa Skill

Voice-first price intelligence for Alexa. Ask about current market prices, analyze historical price trends, get data-driven fair price verdicts, and discover today's top community-voted deals — all powered by the ShopSavvy Data API.

See the full integration page at shopsavvy.com/integrations/alexa.

What It Does

ShopSavvy for Alexa is a price intelligence tool — it gives you objective market data so you can make informed decisions. It does not redirect you to specific stores or tell you where to buy. It surfaces the facts.

Invocation name: "shop savvy"

"Alexa, open shop savvy"
"Alexa, ask shop savvy for the best price on AirPods Pro"
"Alexa, ask shop savvy if 80 dollars is fair for a Kindle"

Intents

1. PriceCheckIntent

Get current market prices across all retailers for any product.

Sample utterances:

• "best price on {product name}"
• "what is the best price for {product name}"
• "current price of {product name}"
• "how much does {product name} cost"
• "market price for {product name}"

Example response: "The lowest available price in the market right now is $249. That's 12% below the 90-day market average of $283. Here are the top current prices across the market: 1. Retailer A at $249, 2. Retailer B at $261, 3. Retailer C at $279."

---

2. IsFairPriceIntent

Get an objective fair price verdict based on current market data and 90-day price history.

Sample utterances:

• "is {price} dollars fair for {product name}"
• "is {price} a good price for {product name}"
• "is {price} dollars reasonable for {product name}"
• "should I pay {price} dollars for {product name}"
• "is that a fair price"

Verdicts: great (near all-time low or 10%+ below average), fair (within 5% of average), high (significantly above average).

Example response: "Based on market data for Sony WH-1000XM5: That is a great price. That's 18% below the 90-day market average — well below typical market conditions. For reference, the current market low is $279, and the 90-day market average is $340. You're looking at $280."

---

3. PriceHistoryIntent

See how a product's price has trended over time, including all-time lows/highs and the 90-day average.

Sample utterances:

• "price history on {product name}"
• "historical prices for {product name}"
• "how has the price of {product name} changed"
• "has {product name} ever been cheaper"
• "when was {product name} cheapest"

Example response: "Here is the price history intelligence for MacBook Air. The all-time market low is $899. The all-time market high is $1,299. The 90-day average is $1,049. Prices have been trending downward over the past 90 days."

---

4. DealAlertIntent

Set a price alert for any product. Requires account linking.

Sample utterances:

• "track {product name}"
• "watch {product name}"
• "alert me when {product name} goes on sale"
• "set a price alert for {product name}"
• "add {product name} to my watchlist"

When the market price drops significantly, you'll be notified via the Alexa app.

---

5. MyWatchlistIntent

Hear the products you're currently monitoring with their current and target prices. Requires account linking.

Sample utterances:

• "my watchlist"
• "what am I tracking"
• "my price alerts"
• "what are my alerts"

---

6. DealOfDayIntent

Hear today's top community-voted deals, ranked by ShopSavvy's voting algorithm.

Sample utterances:

• "today's best deals"
• "best deals today"
• "top deals"
• "hot deals"
• "what's hot right now"

---

7. Standard Intents

Intent	Behavior
LaunchRequest	Welcome message with capability overview
AMAZON.HelpIntent	Full list of what you can ask
AMAZON.StopIntent / CancelIntent	Goodbye
AMAZON.FallbackIntent	Graceful re-prompt with examples
SessionEndedRequest	Clean session teardown

Amazon Certification Strategy

Passing Amazon Alexa certification requires positioning the skill as an information and intelligence tool, not a purchase redirector. ShopSavvy handles this by design:

What we do:

• Surface market pricing data objectively (no preferred retailers)
• Frame all responses as "market intelligence" and "price data"
• Never tell users where to buy or suggest a specific purchase action
• Provide 90-day averages and all-time lows as context for their own decisions
• Use neutral language: "the lowest available price in the market" vs "buy it cheaper at X"

What we never do:

• Suggest a specific retailer over another
• Include affiliate links or preferred merchant promotion
• Use phrases like "buy it at," "purchase from," or "order from"
• Tell the user what they "should" do

Key certification checklist:

• privacyAndCompliance.allowsPurchases is false
• privacyAndCompliance.usesPersonalInfo is false (watchlist uses Alexa User ID only)
• Category is SHOPPING (not UTILITIES — this is appropriate for price check skills)
• Account linking uses Login with Amazon (LWA) OAuth, not custom credential collection
• All APL screens include ShopSavvy branding
• Skill handles all required intents (Help, Stop, Cancel, Fallback, SessionEnded)
• No purchase flow, no in-skill purchasing, no external payment collection
• Privacy policy and terms URLs are live and accessible

Account Linking Flow

DealAlertIntent and MyWatchlistIntent require account linking. Here's the flow:

User: "Alexa, ask ShopSavvy to track AirPods"
         │
         ▼
   Skill checks accessToken
         │
   ┌─────┴─────┐
   │  No token  │ ──▶ Speak: "You need to link your account.
   └───────────┘           I've sent a card to the Alexa app."
                           withLinkAccountCard() → Alexa sends
                           account linking card to Alexa app
         │
   ┌─────┴─────┐
   │ Has token  │ ──▶ Pass accessToken to ShopSavvy API
   └───────────┘     for authenticated operations

Configure account linking in the Alexa Developer Console under Build → Account Linking:

• Authorization URI: https://api.shopsavvy.com/oauth/authorize
• Access Token URI: https://api.shopsavvy.com/oauth/token
• Client ID: your ShopSavvy OAuth app client ID
• Scope: alerts:read alerts:write

APL Visual Documents

On screen-enabled devices (Echo Show, Fire TV, etc.), the skill renders rich visual cards alongside voice responses.

Document	Used by	Shows
price-sparkline.json	PriceCheckIntent	Product name, lowest price, market average, top retailer list
price-history.json	PriceHistoryIntent	All-time low/high, 90-day average, 30-day sparkline timeline
watchlist.json	MyWatchlistIntent	Watchlist items with current vs target price, at-target indicator
deals-carousel.json	DealOfDayIntent	Horizontally scrollable deal cards with grade, savings %, retailer

All APL documents use APL version 1.8, dark theme, and the alexa-layouts import library.

Project Structure

alexa-shopsavvy-skill/
├── lambda/
│   ├── src/
│   │   ├── index.ts                    # Lambda handler entry — skill builder + handler registration
│   │   ├── handlers/
│   │   │   ├── launch.ts               # LaunchRequest
│   │   │   ├── price-check.ts          # PriceCheckIntent
│   │   │   ├── is-fair-price.ts        # IsFairPriceIntent
│   │   │   ├── price-history.ts        # PriceHistoryIntent
│   │   │   ├── deal-alert.ts           # DealAlertIntent (requires account linking)
│   │   │   ├── my-watchlist.ts         # MyWatchlistIntent (requires account linking)
│   │   │   ├── deal-of-day.ts          # DealOfDayIntent
│   │   │   ├── help.ts                 # AMAZON.HelpIntent
│   │   │   ├── stop.ts                 # AMAZON.StopIntent + CancelIntent
│   │   │   ├── fallback.ts             # AMAZON.FallbackIntent
│   │   │   ├── session-ended.ts        # SessionEndedRequest
│   │   │   └── error.ts                # Global error handler
│   │   ├── services/
│   │   │   ├── shopsavvy-api.ts        # ShopSavvy API client (search, prices, history, deals, alerts)
│   │   │   └── response-builder.ts     # APL + voice response helpers, session attribute helpers
│   │   ├── apl/
│   │   │   ├── price-sparkline.json    # APL: price check screen
│   │   │   ├── watchlist.json          # APL: watchlist screen
│   │   │   ├── deals-carousel.json     # APL: deals carousel screen
│   │   │   └── price-history.json      # APL: price history screen
│   │   ├── utils/
│   │   │   ├── ssml.ts                 # SSML helpers (pause, emphasis, sanitize, speakTag)
│   │   │   └── price-formatter.ts      # Price/percent formatting + fair price verdict logic
│   │   └── config/
│   │       └── env.ts                  # Environment config with assertConfig()
│   ├── tests/
│   │   ├── __mocks__/
│   │   │   └── apl-mock.ts             # APL JSON mock for unit tests
│   │   ├── price-formatter.test.ts     # Tests for price formatting + fair price verdict
│   │   ├── ssml.test.ts                # Tests for SSML helpers
│   │   └── handlers.test.ts            # canHandle() routing tests for all handlers
│   ├── package.json
│   └── tsconfig.json
├── skill-package/
│   ├── skill.json                      # Skill manifest (name, category, APL interface, privacy)
│   └── interactionModels/
│       └── custom/
│           └── en-US.json              # Intents, utterances, slots, dialog model
├── ask-resources.json                  # ASK CLI config
├── README.md
├── LICENSE
├── .gitignore
├── .env.example
└── test.sh

Setup

Prerequisites

• ASK CLI (npm install -g ask-cli)
• AWS account with Lambda access
• Amazon Developer account
• ShopSavvy Data API key from shopsavvy.com/data

1. Install dependencies

cd lambda
npm install

2. Configure environment

cp .env.example .env
# Edit .env and set SHOPSAVVY_API_KEY

3. Configure ASK CLI

ask configure

4. Deploy to AWS Lambda

# Deploy skill package and Lambda function
ask deploy

# Or build a zip for manual upload:
cd lambda
npm run build:zip
# Upload alexa-skill.zip to your Lambda function

5. Set Lambda environment variables

In the AWS Lambda console, set:

Variable	Value
SHOPSAVVY_API_KEY	Your ShopSavvy API key
LOG_LEVEL	info (or debug for development)

6. Test in Alexa Developer Console

1. Go to developer.amazon.com
2. Open your skill → Test tab
3. Enable testing
4. Try: "open shop savvy"

Running Tests

./test.sh

The test script runs:

1. File structure checks (all required files present)
2. Interaction model validation (all 7 intents with utterances)
3. APL document JSON syntax validation
4. Skill manifest checks (category, name, APL interface, privacy URLs)
5. Certification framing checks (no purchase-redirection language)
6. TypeScript compilation
7. Jest unit tests (price formatter, SSML utils, handler routing)

For integration tests against the live API:

SHOPSAVVY_API_KEY=ss_live_your_key ./test.sh --integration

Certification Checklist

Before submitting to the Alexa Skills Store:

• All 7 custom intents tested in simulator with multiple utterances each
• Account linking flow tested end-to-end
• APL screens tested on Echo Show 8 and Echo Show 15 form factors
• Fallback intent returns a helpful re-prompt (not an error)
• Help intent covers all capabilities
• Skill ends session cleanly after Stop/Cancel
• No offensive content, no purchase flow
• Privacy policy URL is live: https://shopsavvy.com/privacy
• Terms of use URL is live: https://shopsavvy.com/terms
• Skill icon (108x108 and 512x512) uploaded in Developer Console
• Example phrases in Developer Console match actual supported utterances
• Testing instructions in skill.json are accurate

License

MIT — see LICENSE