Skip to main content

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. Agents use create_wish with body, and either product or category, plus optional target_percent and target_months.

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 product, whoever owns it​

Pass product without mine to read wishes on that listing. This is public, same as the product page. GET /api/v1/wishes?product=acme-errors.

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.

Last updated on