# Cashback for agents

> Get your shopper a tracked cashback link. They open it and buy, the cashback attaches to their account, and they approve every payout.

**Live today: GET /api/v1/links, which mints a tracked cashback link and a claim code. Coming soon, not live yet: the MCP server, agent keys, webhooks, the agent wallet and the other endpoints marked coming soon below.**

- Live endpoint: GET https://sundaypenny.com/api/v1/links?store=<slug>
- Store slugs: https://sundaypenny.com/stores.json
- MCP package: @sundaypenny/mcp (coming soon)
- HTML page: https://sundaypenny.com/agents

## Quickstart

1. **Ask for a link.** No key or SDK yet: call GET /api/v1/links?store=<slug> and read the JSON.
2. **Hand it to your shopper.** They open tracked_url in their own browser before they buy at the store.
3. **Share the claim code.** If they were not signed in, they add the claim code at claim_url within 90 days. Cashback then shows as pending in their account.

## Tracked links (live)

GET /api/v1/links?store=<slug> returns a tracked link for one store and a fresh claim code. No key needed for now; it is rate limited to 30 calls a minute per IP. Store slugs are in /stores.json.

Request:

```bash
curl "https://sundaypenny.com/api/v1/links?store=booking-com"
```

Response:

```json
{
  "store": "booking-com",
  "store_name": "Booking.com",
  "rate": "Up to 7%",
  "status": "estimate",
  "tracked_url": "https://sundaypenny.com/go/booking-com?c=K7MQ-R4",
  "claim_code": "K7MQ-R4",
  "claim_url": "https://sundaypenny.com/claim/K7MQ-R4",
  "terms_url": "https://sundaypenny.com/store/booking-com#terms-heading",
  "claim_window_days": 90,
  "created_at": "2026-11-17T09:41:12.000Z",
  "notes": [
    "…"
  ]
}
```

- `tracked_url`: Give this to the shopper to open in their own browser before they buy. It records the visit and sends them on to the store.
- `claim_code`: Short code, four characters, a dash and two more, with no 0, O, 1 or I so it can be read out or typed. It ties the trip to the shopper.
- `claim_url`: Where the shopper adds the trip to their Sunday Penny account, within 90 days. Signed-in shoppers who open tracked_url are attached automatically.
- `rate`: The store's cashback rate as shown on the site. status is always "estimate": rates are not guaranteed offers.
- `terms_url`: The store's cashback terms on its Sunday Penny page.

### How the claim works

1. **Get a tracked link.** Call GET /api/v1/links?store=<slug>. Each call mints a new claim code, so ask once per shopping trip.
2. **The shopper opens it and buys.** Hand tracked_url to the shopper. They open it in their own browser right before they buy; it takes them straight to the store. Automated fetchers get a plain page with the same deal and no visit is counted, so the link only works when a person opens it.
3. **The shopper claims it.** Signed in to Sunday Penny when they open the link? The trip is theirs already. Otherwise they open claim_url, sign in or create an account, and add it. They have 90 days.
4. **Cashback shows as pending.** When the store reports the order, the shopper's share of the commission (80%) shows in My money as pending. Pending until the store confirms, typically 30 to 90 days.

No affiliate network is connected yet. Links go to the store's own homepage with a placeholder tracking parameter, so no orders are reported and no cashback is paid in this demo.

## MCP server (coming soon)

Not live yet. When it ships it will work with Claude, ChatGPT, Cursor and any client that speaks MCP. The planned config:

```json
{
  "mcpServers": {
    "sundaypenny": {
      "command": "npx",
      "args": ["-y", "@sundaypenny/mcp"],
      "env": {
        "SUNDAYPENNY_API_KEY": "drk_test_…"
      }
    }
  }
}
```

### Planned tools

- `search_stores({ query, category? })`: Find stores by name, category or shopping intent. Each result carries the current rate and an agent_ready flag.
- `get_rate({ merchant })`: Current cashback rate for one merchant, including any upsized offer.
- `create_cashback_link({ merchant, intent? })`: Returns a tracked link and claim code, like GET /api/v1/links does today. Once agent keys exist, the cashback will attach to the user who linked the agent.
- `get_wallet()`: Read-only balance, pending cashback and the per-agent ledger. There is no withdraw tool.

## More endpoints (coming soon)

A keyed API at `https://api.sundaypenny.demo`, authenticated with an agent key as a bearer token. Not live yet.

- `GET /v1/stores`: Search stores and rates
- `GET /v1/rates/{merchant}`: Current rate for one merchant
- `GET /v1/wallet`: Balance and per-agent ledger

## In-store offers (concept)

Agents can read the in-store offers at /offers.json and add offers to the shopper's list on their behalf. The shopper still buys in store and scans the receipt themselves, and the cashback lands in their wallet. The add_instore_offer tool and POST /v1/instore/list are a concept, like the rest of this API. Offers: https://sundaypenny.com/offers.json. Page: https://sundaypenny.com/instore. Markdown: https://sundaypenny.com/instore.md.

- `add_instore_offer({ offer })`: Adds one offer, named by its slug in /offers.json, to the shopper's in-store list. It cannot scan receipts or withdraw.
- `POST /v1/instore/list`: Add an offer to the shopper's in-store list

Request:

```bash
curl -X POST https://api.sundaypenny.demo/v1/instore/list \
  -H "Authorization: Bearer $SUNDAYPENNY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "offer": "vegemite-280g" }'
```

Response:

```json
{
  "offer": "vegemite-280g",
  "on_list": true,
  "offers_on_list": 1,
  "tracked_for": "usr_demo",
  "agent": "agt_grocery_bot"
}
```

## Webhooks (coming soon)

Not live yet. Each request will carry a `SundayPenny-Signature` header, an HMAC-SHA256 of the raw body.

- `cashback.tracked`: The merchant reported an order made through your link. Cashback is pending.
- `cashback.confirmed`: The order cleared the return window. Cashback is payable, with your approval.

## Agent wallet (coming soon)

- Every agent gets its own spend and cashback ledger, plus a monthly cap you set.
- Agents can read the wallet. Only you can withdraw from it.
- Spending caps: links stop being issued once the cap is reached.
- You approve payouts: withdrawals need your sign-off in the app.

## FAQ

**Who gets the cashback?** The shopper whose Sunday Penny account the trip is attached to: automatically if they are signed in when they open the tracked link, or when they add the claim code at the claim page within 90 days. Never the agent or the developer who built it.

**Can agents withdraw?** No. The live endpoint only creates links. There is no withdraw tool or endpoint, and payouts will only move after the shopper approves them in the app.

**Which stores work with agents?** GET /api/v1/links works for every store. Stores flagged agent-ready also accept purchases an agent starts itself; in this demo that is 18 stores, marked agentReady in /stores.json. Browse them on the stores page.

**How does attribution work?** GET /api/v1/links mints a claim code and a tracked_url carrying it. When the shopper opens the link, we record the visit and pass the code to the store's affiliate network as its tracking reference. The network reports the order back with that code, and the cashback shows as pending, then confirmed or declined once the store's return period ends. No network is connected yet, so in this demo no orders are reported.

**Is it free?** Yes. Getting a link costs nothing, and cashback is a share (80%) of the commission stores already pay for referred sales.

---

Concept demo. Store names and logos belong to their respective owners. Cashback rates shown are illustrative only.
