paperclip-subscriptions

A Paperclip plugin that tracks fixed monthly subscription costs alongside Paperclip's inference spending panel.

Paperclip already tracks per-token API usage, but infrastructure running on flat monthly plans (e.g. Claude MAX, ChatGPT Plus, Google AI Pro) shows as $0. This plugin adds a dedicated page, dashboard widget, and automatic finance events so you can see your full AI infrastructure spend at a glance.

Features

• Summary cards — monthly total, annual projection, active subscription count, next renewal date
• Subscriptions table — name, provider, amount/month, renewal day with inline edit and delete
• Full inline editing — edit all fields (name, provider, amount, start date, notes) without leaving the page
• Analytics panels — upcoming renewals with urgency highlight, breakdown by provider with progress bars, subscriptions vs API spend comparison
• Dashboard widget — compact monthly total card on the Paperclip home dashboard
• Finance integration — automatically creates platform_fee debit events in Paperclip's Costs → Finance tab each month; issues credit events when a subscription is removed or its amount changes mid-month
• Billing cycle tracking — startDate sets the renewal day-of-month (e.g. subscribed on the 5th → renews every 5th)
• Persistent storage — data survives restarts via Paperclip's native plugin state (PostgreSQL-backed)
• No core modifications — fully isolated plugin; Paperclip can receive updates normally

Installation

npx paperclip-subscriptions

If Paperclip runs on a non-default address, set PAPERCLIP_URL:

PAPERCLIP_URL=http://my-server:3100 npx paperclip-subscriptions

Usage

1. Open your company dashboard in Paperclip
2. Click Subscriptions in the sidebar
3. Click + Add to register a subscription
4. Fill in the name, provider, monthly amount in USD, and start date
5. The finance tab and dashboard widget update automatically

To edit a subscription, click the pencil icon (✏) on any row — all fields are editable inline.

Supported providers

Provider	Key
Anthropic	anthropic
OpenAI	openai
Google	google
OpenRouter	openrouter
Other	other

Finance integration

Each month (on first page load), the plugin records a platform_fee debit event per active subscription in Paperclip's finance ledger. If you remove a subscription or change its amount after the month was already recorded, the plugin automatically issues a correcting credit so the ledger stays accurate.

Finance events appear in Costs → Finance filtered by month.

Data model

Each subscription stores:

{
  "id": "uuid",
  "name": "Claude MAX",
  "biller": "anthropic",
  "amountCents": 10000,
  "currency": "USD",
  "startDate": "2026-04-05",
  "notes": "optional free-text",
  "createdAt": "2026-04-28T00:00:00.000Z"
}

Data is scoped per company and stored in Paperclip's plugin state (PostgreSQL-backed).

Development

npm install
npm run build

TypeScript source files are in src/:

• src/manifest.ts — plugin metadata and UI slot declarations
• src/worker.ts — action handlers (list, add, update, remove, recordMonth) via ctx.state and ctx.finance
• src/ui/index.tsx — React components (SubscriptionsPage, SubscriptionsWidget, SubscriptionsSidebarItem)

Requires @paperclipai/plugin-sdk and a running Paperclip instance to test against.

License

MIT