# Share a Wish Developer Docs

> Share a Wish adds a cross-device wishlist to any online shop: a Save Button SDK (one script tag + public key), a REST Wishlist API (OpenAPI 3.1), hosted share pages and a Shopify app. Plans are metered in wishlist actions per month; requests are never rejected with 429. Paid plans pay per additional action above the quota (Starter 2.5 ct, Growth 1.0 ct, Scale 0.5 ct); the Free plan (200 actions) is paused at 100% and POST /widget/save answers 402 usage_limit_reached.

Base URL: https://nqwfhjycwrtukfszuofi.supabase.co/functions/v1/public-api (single production environment; test keys use the same server).

## Guides

- [Overview](https://shareawish.shop/developers/): getting started, authentication at a glance, endpoint overview
- [Add to Wishlist Save Button](https://shareawish.shop/developers/save-button/): drop-in script, data-shareawish attributes, init()/open(), events (saved, close, open, error), React via @shareawish/widget, Shopify Liquid snippet
- [Wishlist API](https://shareawish.shop/developers/wishlist-api/): keys and tokens, POST /widget/init, POST /widget/save, GET /widget/saved-products, hosted list CRUD, GET /hosted/public/lists/{token}, with request/response examples
- [Hosted Wishlists & Share Links](https://shareawish.shop/developers/hosted-lists/): create lists, share tokens (https://shareawish.de/{lang}/list/{token}), public view without account, mark-as-purchased, Open Graph previews
- [Shopify Wishlist App](https://shareawish.shop/developers/shopify/): install flow, theme app extension blocks (Setup app embed, Button, Basket, Float, Header), plans Free 200 / Starter 2,000 / Growth 15,000 / Scale 60,000 actions, 14-day trial
- [Rate Limits & Usage](https://shareawish.shop/developers/rate-limits/): wishlist actions (save, share, list_view), per-plan limits, per-action overage on paid plans, Free-plan hard stop (402 usage_limit_reached), 80% / 100% notifications, X-RateLimit-* and X-Usage-* headers
- [Error Codes](https://shareawish.shop/developers/errors/): every error code with HTTP status and meaning, including ad_studio_disabled (410)
- [MCP Servers](https://shareawish.shop/developers/mcp/): two Model Context Protocol stdio servers in npm package @shareawish/mcp — Creator Shop server (shareawish-creator-mcp: handle check, shops, logo/cover upload, lists, products by URL with affiliate links, product videos, analytics, earnings) and Wishlist Integration server (shareawish-wishlist-mcp: API keys and allow-lists, widget_init_check, basket configs, embed snippets, usage, docs/OpenAPI search); install with npx -y -p @shareawish/mcp <bin>; auth via SHAREAWISH_TOKEN personal access token (saw_pat_…) from Partner Portal → API & Integrations → Access tokens; free on every plan; source https://github.com/shareawish/mcp

## Reference

- [Interactive API reference](https://shareawish.shop/developers/reference.html): Scalar UI rendered from the OpenAPI spec
- [OpenAPI 3.1 YAML](https://shareawish.shop/openapi/shareawish-public-api.yaml): machine-readable spec, version 1.1.0
- [Endpoint summary JSON](https://shareawish.shop/openapi/summary.json): operations grouped by tag with auth, audience and docs anchors
- [Changelog](https://shareawish.shop/developers/changelog.html)

## SDK

- Save Button SDK (canonical): https://shareawish.shop/sdk/v1/widget.js (IIFE, exposes window.ShareAWish; v1 alias receives backwards-compatible updates)
- Basket integration SDK: https://shareawish.shop/sdk/v1/basket-integration.js (window.ShareWishBasket)
- npm package: @shareawish/widget (ESM/CJS, exports init, mount, open, on, off, createInstance, autoInit, VERSION, CDN_URL)
- Hosted save dialog: https://shareawish.shop/save · hosted basket: https://shareawish.shop/basket
- Deprecated URLs (301 to canonical): https://shareawish.shop/sdk/save-sdk.js, https://cdn.shareawish.shop/sdk/v1/save-sdk.js, https://cdn.shareawish.com/widget.js

## Authentication basics

- Public key: `Authorization: Bearer pk_live_…` or `pk_test_…`. Used for POST /widget/init and GET /api-usage/{apiKeyId}. Safe in browsers. Test keys work on every plan and on localhost; live keys created after 2026-09-01 need a domain allow-list.
- Widget token: `X-Widget-Token: <jwt>` returned by POST /widget/init (10-minute TTL, bound to the page origin). Required for /widget/* after init.
- User token: `Authorization: Bearer <supabase access token>` of the end user. Required for everything that reads or writes a user's lists (/widget/save, /hosted/*, /me/*).
- Errors: JSON `{ "error": "<snake_case_code>", "message"?: string }` with 4xx/5xx status. Common: invalid_input 400, unauthorized 401, usage_limit_reached 402 (Free plan paused at 100%, /widget/save only), unknown_key / origin_not_allowed / allowlist_required / subscription_required 403, invalid_wishlist 403, not_found 404, product_create_failed 500.

## Optional

- [Partner Portal](https://partner.shareawish.shop): create API keys, configure the basket, see usage
- [Site-wide llms.txt](https://shareawish.shop/llms.txt)