Wishlist API & Save Widget

Add a cross-device wishlist to any store in an afternoon. One script tag, one public key, and a REST API for everything else.

Add the Save Button Browse the API reference

OpenAPI 3.1 · … documented operations · base URL https://nqwfhjycwrtukfszuofi.supabase.co/functions/v1/public-api

Guides

Save Button

Embed widget.js, data-shareawish attributes, init(), events, React and Shopify Liquid.

Wishlist API

Keys and tokens, /widget/init, /widget/save, saved products, hosted list CRUD with real payloads.

Hosted Wishlists & Share Links

Create lists, share by token, public view without account, mark as purchased, Open Graph previews.

Shopify Wishlist App

Install flow, the five theme app extension blocks and their settings, plans and the 14-day trial.

Rate Limits & Usage

Wishlist actions as the billing unit, per-plan limits, 80% / 100% notifications, X-RateLimit-* and X-Usage-* headers.

Error Codes

Every error code with HTTP status and meaning, from origin_not_allowed to ad_studio_disabled.

MCP Servers

Use Share a Wish from Claude, Cursor or Copilot: @shareawish/mcp ships a Creator Shop server and a Wishlist Integration server, installed via npx, authenticated with a personal access token.

Getting started in three steps

1. Create a test key

In the Partner Portal open API & Integrations → API Keys and create a key with environment Test. You get a pk_test_… key. Test keys work on every plan, can be used on localhost and staging domains and hit the same live API as production keys — there is no separate sandbox, so the data you save is real.

Production keys (pk_live_…) need at least one allow-listed domain when created after 2026-09-01; POST /widget/init rejects other origins with origin_not_allowed.
2. Embed the Save Button
```
<script src="https://shareawish.shop/sdk/v1/widget.js" data-shareawish-key="pk_test_xxx" defer></script>

<button data-shareawish
        data-url="https://shop.example.com/p/trail-shoes"
        data-title="Trail Running Shoes"
        data-image-url="https://shop.example.com/img/shoes.jpg"
        data-price="12999"
        data-currency="EUR">
  Save to wishlist
</button>
```
Or programmatically: ShareAWish.init({ key: 'pk_test_xxx' }) and ShareAWish.open({ productUrl, title, imageUrl, price, currency }) from a click handler. The SDK calls POST /widget/init with your key and the page origin, receives a 10-minute widget token and opens the hosted save dialog at https://shareawish.shop/save. Details: Save Button guide.

Canonical SDK URL: https://shareawish.shop/sdk/v1/widget.js. Legacy URLs (/sdk/save-sdk.js, cdn.shareawish.shop/sdk/v1/save-sdk.js, cdn.shareawish.com/widget.js) and the data-saw-key attribute are deprecated.

3. Show the basket

<script src="https://shareawish.shop/sdk/v1/basket-integration.js"></script>
<script>
  ShareWishBasket.init({
    apiKey: 'pk_test_xxx',
    configId: 'bkt_xxx',            // from Partner Portal → Basket
    cartUrl: 'https://shop.example.com/cart/add?id={variant_id}&qty={quantity}'
  });
</script>

The basket reads its configuration from GET /baskets/{id}, tracks opens/checkouts via POST /baskets/{id}/event and lists the user's products saved from your shop through GET /widget/saved-products.

Authentication at a glance

Token	Header	Used for
Public key	`Authorization: Bearer pk_live_… \| pk_test_…`	`POST /widget/init`, `GET /api-usage/{id}`. Safe in browsers.
Widget token	`X-Widget-Token: <jwt>`	All `/widget/*` calls after init. Bound to the page origin, 10 min TTL.
User token	`Authorization: Bearer <supabase access token>`	Everything that reads or writes a user's lists (`/widget/save`, `/hosted/`, `/me/`).

Full details, request and response examples: Wishlist API.

Rate limits & usage

Plans are metered in wishlist actions per month — a save, a share or a hosted list view — from 200 on Free to 60,000 on Scale. Requests are never rejected with 429; you are notified at 80% and 100% of the quota. Paid plans keep working above the quota and pay per additional action (Starter 2.5 ct, Growth 1.0 ct, Scale 0.5 ct); the Free plan is paused at 100% and POST /widget/save answers 402 usage_limit_reached. Responses on /widget/*, /hosted/*, /shops/* and the basket routes carry informational X-RateLimit-* and X-Usage-* headers. See Rate Limits & Usage.

Endpoint overview

Generated from the OpenAPI spec. Endpoints tagged consumer or internal serve the Share a Wish app and portal and are documented for completeness; the partner-facing surface is Widget, Hosted, Baskets, Shops, Discover and Stores.

Loading /openapi/summary.json…

Errors

Errors are JSON with a machine-readable code: { "error": "origin_not_allowed" }, optionally with message. Common codes: invalid_input (400), unauthorized (401), origin_not_allowed / unknown_key / allowlist_required / subscription_required (403 on /widget/init), invalid_wishlist (403), not_found (404), product_create_failed (500, includes db_error). Complete list: Error Codes.