Hosted Wishlists & Share Links

Creating a hosted list

Lists belong to an end user, so every write needs the user's Supabase access token (Authorization: Bearer …). A list is created with a name and optional description; the response contains the new share token.

POST /hosted/me/lists
Authorization: Bearer <supabase access token>
Content-Type: application/json

{ "name": "Birthday", "description": "Ideas for my birthday" }

→ { "ok": true, "list": { … }, "token": "k3Jd9…" }

Then add products with POST /hosted/save (same contract as /widget/save, user token only) using the list's numeric db_id as wishlistId. POST /hosted/lists returns all lists the user owns or edits, including db_id, productCount, share_public and the collaborator role. Metadata can be changed with PUT /hosted/lists/{token} (name, description, share_public, image_path, occasion_slug) and a list is removed with DELETE /hosted/lists/{token} (owner only). Field-level details are on the Wishlist API page.

Share tokens and URLs

Each list has a share token — the id returned by /hosted/lists and the {token} path parameter of all list endpoints. A list becomes shareable when share_public is set to true; sharing counts as one share wishlist action per list and day.

The public page lives on the consumer site. The Open Graph route builds the canonical page URL as https://shareawish.de/{lang}/list/{token}, for example:

https://shareawish.de/de/list/k3Jd9…
https://shareawish.de/en/list/k3Jd9…

Use these URLs when you surface a "share your list" link from your own UI. Do not construct URLs from the numeric db_id; only the token is public.

Public view without an account

Two endpoints power the share page and need no authentication at all. They only return lists whose share_public flag is true; anything else answers 404 not_found.

Both accept market (e.g. de-DE) and lang query parameters for localized titles and prices. A public list view is metered as one list view wishlist action per list, viewer and 10-minute window (see usage).

Signed-in users can additionally follow a public list with POST /hosted/public/lists/{token}/link (viewer role, auto-friends the owner) and unfollow with DELETE on the same path.

Mark-as-purchased flow

Gift-givers can tick off an item on the public page so nobody buys the same present twice. The endpoint is unauthenticated and works on public lists only:

PUT /hosted/public/lists/k3Jd9…/items/98765/purchased
Content-Type: application/json

{ "purchased": true }

→ { "ok": true, "purchased": true }

itemId is the item_id from the items response (not the product id). Sending { "purchased": false } reverts the flag. The list owner sees the same flag through the authenticated PUT /hosted/lists/{token}/items/{itemId}/purchased, and items come back with purchased: true in every items response.

Open Graph link previews

When a share link is posted in a chat or on a social network, the crawler receives a minimal HTML document with og:* and twitter:* tags instead of the JavaScript app:

GET /og/list/{token}?lang=de|en        → text/html with og:title, og:description, og:image, og:url
GET /og/image/{file}                   → the rendered preview image (falls back to a default image)

The document sets og:type=website, og:site_name, a localized og:locale (de_DE / en_US), og:url and link rel=canonical pointing to https://shareawish.de/{lang}/list/{token}, plus a generated image with fixed width and height. Human visitors are redirected to the page immediately (meta refresh + location.replace). You do not need to call these routes yourself; they are what bots get when they fetch a share URL.