Wishes
A wish is a request, not a coupon. Dealpuffin does not mint a code to satisfy it.
Two kinds
On a product. You are on that product's listing. The wish inherits the product's category. Write what you want.
Open. You are not asking one product. Pick a category and describe the coupon. Providers in that category can see it.
Both can carry an optional target: a percent off, or a number of months free. The target is a hint. The provider still has to publish a Stripe coupon that matches what they are willing to offer.
Who can file one
A signed-in user on the website. Agents can list_wishes to read demand; filing a wish stays human-initiated on dealpuffin.com.
What an agent can read
list_wishes is two checks. Do both before suggesting a coupon. Neither check returns a promotion code.
Open wishes in a category
Pass category as a category or subcategory slug. A parent category includes open wishes filed on its subcategories. Each row has category_slug and category_name. These wishes are not attached to one product.
{ "category": "engineering" }
The same read is public: GET /api/v1/wishes?category=engineering. No bearer token.
Wishes on products this account submitted
Pass mine: true. Each row has product_slug, product_name, category_slug, and category_name, so the agent can tell which listing the wish is on. Add category to keep products in that category. A parent category includes its subcategories. Add product to keep one listing this account owns.
{ "mine": true }
{ "mine": true, "category": "engineering" }
GET /api/v1/wishes?mine=1 needs Authorization: Bearer and the list_wishes tool on that key. category and product are optional query parameters on that same URL.
One public product
Pass product without mine to read wishes on a public https listing (pending or verified). GET /api/v1/wishes?product=acme-errors is the public read, and it is empty unless that listing is public.
How a provider answers
Publish a real coupon from Stripe onto the product. There is no separate "grant wish" object. The offer shows up when that coupon is published and eligible. A wish on your product is answered by a coupon on that product. An open wish in a category is answered by a coupon on one of your products in that category.
Frequently asked questions
How does an agent see wishes in a category?
Call list_wishes with category set to the category or subcategory slug. A parent category includes open wishes on its subcategories. This call does not need an API key.
How does an agent see wishes on the products I submitted?
Call list_wishes with mine set to true, using a key that has list_wishes. The rows are wishes filed on listings this account owns. Pass category or product on that same call to narrow them.