# Widget and API

> Show your ReceiptFold spend on your own website with a read-only widget, or read the same numbers from your server with the API. Keys, allowed origins, options and examples.

## The widget

A read-only box that shows this workspace's spend on a site of yours, drawn from the same numbers as Spend: total and monthly average, this month against the previous, subscriptions, a monthly chart, and where the money goes by vendor or by category, with the vendors' logos. Light or dark, English or Spanish. Visitors can switch the view (Spend, Vendors, Subscriptions), the period (3, 6 or 12 months) and the currency. The widget is available on the Pro plan and above; on Business and Scale it can carry your own logo instead of "Powered by ReceiptFold".

### Set it up

1. Settings → **Widget & API**. Under "Where will it be shown?" list the origins, one per line: scheme and host, no path (for example `https://intranet.example.com`). `http://localhost` is accepted for development. Up to 10 origins.
2. Create a **public key**. It only works on the origins you list, so a copied key is useless elsewhere.
3. Paste one of the two snippets into your page.

Script (draws the widget right after its tag; in a React or Vite app put it in `index.html`, just before `</body>`):

```html
<script src="https://app.receiptfold.com/widget.js"
  data-key="sl_pub_…" data-view="spend"
  data-months="6" data-theme="auto"></script>
```

Iframe (no script needed):

```html
<iframe src="https://api.receiptfold.com/embed?key=sl_pub_…&view=spend&months=6&theme=auto"
  style="width:100%;max-width:640px;height:360px;border:0" title="ReceiptFold"></iframe>
```

### Options

| Attribute | Values |
| --- | --- |
| `data-view` | `spend` (default), `subscriptions` or `vendors` |
| `data-months` | Window in months, 1 to your plan's history (default 6) |
| `data-currency` | The currency to open on (USD, UYU…); default: the one with the most receipts |
| `data-lang` | `en` or `es` (default: the page language) |
| `data-theme` | `light`, `dark` or `auto` (default `auto`) |
| `data-target` | A CSS selector: draw the widget inside that element instead of after the tag |
| `data-filters` | `off` hides the quick filters (view, period, currency) |

From your own code, for apps that render their box later:

```js
ReceiptFoldWidget.mount('#spend', { key: 'sl_pub_…', view: 'spend', months: '6', lang: 'es', theme: 'dark' });
```

Hosts can theme the widget with CSS custom properties on the host element: `--rf-ink`, `--rf-surface`, `--rf-surface-muted`, `--rf-muted`, `--rf-emerald`, `--rf-danger`, `--rf-hairline`, `--rf-radius`, `--rf-font`, `--rf-font-mono`.

## The API

For your own servers: the same JSON the widget reads, with a **secret key** sent as a Bearer token. The API is available on Business and Scale. Never put a secret key in a browser; the API refuses it there.

```bash
curl -H "Authorization: Bearer sl_sec_…" "https://api.receiptfold.com/v1/widget/view?view=spend&months=6"
```

`view`, `months` and `currency` take the same values as the widget. A key is shown once, right after you create it; revoke it in the same screen. Up to 25 keys per workspace.

The payload holds totals, vendor names and categories only: never receipt numbers, email addresses, sources or file links.