Shop Notify

Shop Notify watches an Etsy shop and tells you – and anyone else you like – as soon as new items appear. Perfect for one-of-a-kind pieces that sell out quickly.

• New items and items back in the shop: every listing is reported once; if it is gone for more than a day and comes back, you hear about it – with its previous price and when it was last seen.
• Any notification channel: HTML e-mail with item images to as many recipients as you want, push to your phone via ntfy, Telegram, Signal and 100+ more – also several at once.
• Runs unattended: made for a Raspberry Pi, as a Docker container or systemd service, with health check, watchdog and Etsy rate-limit handling.

How it works

Every few minutes Shop Notify fetches the active listings of the shop from the Etsy Open API v3 and compares them with the items it has already seen. Each new item is notified exactly once:

First run

When the database is empty, all items currently in the shop would be "new". Instead of flooding your phone, Shop Notify only records them on the first run and prints them to the console; notifications start with the next new item:

First run: 87 items currently in YourShop (recorded, not notified)
…

Set NOTIFY_EXISTING_ON_FIRST_RUN=true to send them to all targets anyway. To start over, delete the database (DB_PATH).

Example notification

A notification on your phone (plain text) looks like this – e-mails additionally show the item picture:

2 new items in YourShop

Hand-thrown mug "Morning dew"
€24.50 · Oct 14, 2026, 19:46
https://www.etsy.com/listing/1234567890

Small vase in sage green
€18.00 · Oct 14, 2026, 20:46
https://www.etsy.com/listing/1234567891

Quick start

1. Get an Etsy API key – see Creating an Etsy app. You need the keystring and the shared secret.

2. Configure: download compose.yaml and .env.example, save the latter as .env and fill in your key, secret and the shop name (as in etsy.com/shop/<name>).

3. Start:

   mkdir -p data
   docker compose up -d
   docker compose logs -f
   

Without notification targets, new items are only written to the log – a good first test. Then set up notifications.

Configuration

All settings are read from .env in the working directory or from environment variables (which take precedence).

Only listing ID, title, URL, price and modification time are stored locally; vanished listings are deleted once they were notified.

Choosing the poll interval

A new Etsy app may make 5,000 requests per day. Every poll needs one request per 100 active listings, so stay above 35 s × pages to use at most half of the quota:

The default of 5 minutes needs fewer than 300 requests per day for a typical shop. Shop Notify logs a warning when less than 20 % of the daily quota is left, and waits as long as Etsy asks when it answers 429 Too Many Requests.

Notifications

Notifications are sent with Apprise – e-mail, ntfy, Telegram, Signal and 100+ more. Copy notify.example.yml to notify.yml, adjust it and set NOTIFY_CONFIG=notify.yml:

version: 1
urls:
  # One e-mail to several people who don't see each other's address
  - mailtos://you:app-password@gmail.com:
      - bcc: alice@example.com, bob@example.com
  # Push notification to your phone
  - ntfys://ntfy.sh/your-long-random-topic

E-mail gets one HTML message with all new items; push and chat services get one message per item with its picture. Try your setup with shop-notify test-notify – no Etsy key needed.

→ Notifications in detail: setting up Gmail, ntfy and Telegram, pictures and summaries, testing, custom templates and languages.

Creating an Etsy app

Shop Notify only reads public listings, so it needs an API key (keystring and shared secret) but no OAuth login. New apps start as Pending Personal Approval; until they are Active, every request fails with 403. → Step-by-step registration

Running

Docker

Images for linux/amd64 and linux/arm64 (Raspberry Pi with a 64-bit OS) are published as ghcr.io/spielkind/shop-notify (latest = newest release). With compose.yaml and your .env:

mkdir -p data
docker compose pull
docker compose up -d
docker compose logs -f

To use notify.yml, uncomment its volume in compose.yaml and set NOTIFY_CONFIG=/config/notify.yml; set TZ=Europe/Berlin (or your time zone) as the container runs in UTC otherwise. → Docker in detail: image tags, updates, moving an existing database, verifying the image, troubleshooting.

systemd

Alternatively install it as a sandboxed systemd service, e.g. on Raspberry Pi OS; systemctl status then shows the result of the last poll. → systemd setup

Locally

Install it from PyPI with uv (it downloads Python 3.14+ if needed) or pipx:

uv tool install shop-notify    # or: pipx install shop-notify
# create .env in the current directory (see .env.example) and fill it in
shop-notify

Update with uv tool upgrade shop-notify. To run it from a clone of the repository instead: uv sync, then uv run shop-notify.

Stop it with Ctrl+C.

History

Shop Notify keeps a history of every listing – when it appeared, was notified, went missing, was gone or came back, and price and title changes – and a log of the polls of the last 14 days:

shop-notify history                      # events of the last 7 days
shop-notify history 1550875589           # everything about one listing
shop-notify history --since 2w           # a longer period (m, h, d, w)
shop-notify history --polls --since 1d   # the polls, e.g. incomplete answers from Etsy
docker compose exec shop-notify shop-notify history   # in Docker

2026-10-21 09:07   1550875589  new            Mermaid Dreams- 5 x 7 Mini Art Print  (price: 24.99 USD, created: 2023-08-23 19:26, …)
2026-10-23 14:00   1550875589  price_changed  Mermaid Dreams- 5 x 7 Mini Art Print  (old: 24.99 USD, new: 19.99 USD)

Nothing before the first run is known (Etsy has no history), and changes are only noticed at the next poll. The database layout is described in docs/architecture.md.

Health check

After every successful poll Shop Notify touches a heartbeat file. shop-notify healthcheck exits with 0 if the last successful poll is younger than 2 × POLL_INTERVAL + 60 s, otherwise with 1 – e.g. when Etsy rejects the API key or the network is down. Docker uses it for its health status; manually:

shop-notify healthcheck                              # local
docker compose exec shop-notify shop-notify healthcheck   # Docker

FAQ

Development

uv sync
uv run pre-commit install
uv run pytest

See CONTRIBUTING.md for the development workflow, pull requests and releases. Planned features are on the roadmap; security issues please report as described in SECURITY.md.

• Architecture and security model
• Governance and Code of Conduct

License and disclaimer

MIT.

The term "Etsy" is a trademark of Etsy, Inc. This application uses the Etsy API but is not endorsed or certified by Etsy, Inc.