Zappier — Operations & Usage Manual

Version: 0.2.0 · Last updated: 2026-07-28

Zappier is a metered API platform: every API call your customers make is priced per endpoint, adjusted by their customer type, tracked in a usage ledger, and billed through Stripe once a day — or invoiced manually by purchase order. Customers self-serve through the portal at /portal. This manual covers running and operating the system. For internals, see DEVELOPER.md; for accounting procedures see ACCOUNTING.md; for the end-user view see CUSTOMER-PORTAL.md.

Table of contents

1. Quick start
2. The three surfaces
3. How pricing works
4. Operating the Pricing Admin UI
5. Using the public API
6. Billing operations (Stripe)
7. The Zapier integration
8. Day-to-day runbook
9. Troubleshooting

1. Quick start

cd /Users/marchon/zappier
npm install
npm run dev          # starts the API on http://localhost:3000

Environment variables (all optional except STRIPE_SECRET_KEY for billing):

All runtime paths (database default, .env, OpenAPI spec, static assets) resolve from the installation root — the compiled server (node dist/index.js) runs from any working directory, under systemd, Docker, or cron.

The .env file at the repo root holds STRIPE_SECRET_KEY. It is gitignored and owner-only (chmod 600). A template is in .env.example.

On first start the database is created and seeded with:

• Rate card: status (free), storage-list (free), transform (fixed 4¢), storage (variable: 10¢ base + 1¢/KB metadata + 50¢/MB attachments)
• Customer types: Free (×1.0, 100¢/month credit), Pro (×0.5, 1000¢ credit), Business (×0.25, 10000¢ credit)
• Demo customers: key-ada (Free), key-grace (Pro), key-linus (Business)

Seeding only happens into an empty database. Existing data is never overwritten on restart.

2. The three surfaces

3. How pricing works

Every priced call returns its quote in the response, so customers always know what a call cost:

{
  "quote": {
    "endpointId": "storage",
    "listCents": 62,
    "totalCents": 31,
    "breakdown": { "baseCents": 10, "metadataCents": 2, "attachmentCents": 50 }
  }
}

The price of a call is computed in three steps:

1. Endpoint rule (from the rate card):
   • free — always 0¢
   • fixed — a flat fixedCents per call
   • variable — baseCents + perKbCents × ceil(metadata bytes / 1024)
     • perMbCents × ceil(attachment bytes / 1 MB)
2. Customer-type multiplier — totalCents = round(listCents × multiplier). A per-customer multiplier override (set in the Customers tab) wins over the type multiplier — use it for negotiated enterprise deals.
3. Monthly credit — at billing time, each customer’s type credit (e.g. Pro = 1000¢) is subtracted from their month-to-date total. Only the excess is billed.

Worked example. A Pro customer (×0.5) uploads a 1 MB file with 2 KB of metadata to storage:

• list = 10¢ base + 2¢ metadata + 50¢ attachment = 62¢
• Pro multiplier: 62 × 0.5 = 31¢ charged to their usage ledger
• If their month-to-date is 1500¢ and the Pro credit is 1000¢, the daily billing job reports 500¢ to Stripe.

4. Operating the Pricing Admin UI

Open http://localhost:3000/admin and sign in. Two accounts are available:

Sessions are token-based and remembered in browser local storage until you click Sign out or the server restarts (tokens are in-memory — just sign in again). The legacy x-admin-key header still works for scripts and curl.

4.1 Rate card tab

One row per API endpoint (matched by OpenAPI operationId).

• Change a price: edit the kind (free / fixed / variable) and the cent fields, then click Save. Takes effect on the next API call — no restart needed.
• Add an endpoint: enter the operationId (must match openapi.yaml), pick a kind, click Add.
• Delete removes the rule. If an endpoint has no rule and the customer’s type has no default rule, calls to it are rejected with 403 — deletion is how you turn an endpoint off.

4.2 Customer types tab

Types are your pricing tiers.

• Multiplier scales every price for that type (0.5 = 50% of list).
• Monthly credit (cents) is the free included usage per month.
• Add customer type: id, name, multiplier. New types start with 0 credit; edit after adding.

4.3 Customers tab

• Create a customer: name + type. The API key is shown once in the status line at the bottom — copy it immediately and send it to the customer.
• Change type with the dropdown, then Save.
• Email — used for portal sign-in/claiming and email invoicing.
• Billing — Stripe (metered by the daily job) or Purchase order (manual invoicing with PO numbers; see ACCOUNTING.md).
• Multiplier override: a number here replaces the type multiplier for this customer only. Leave blank to inherit from the type.
• Stripe customer IDs are attached via the admin API (PUT /admin/api/customers/:id with {"stripeCustomerId": "cus_..."}) — see section 6.

4.4 Invoices, Reports, System tabs

The Invoices tab generates monthly invoices from metered usage (per period, optionally per customer, with optional PO number), walks them draft → issued → paid, and opens print-ready invoice pages. The Reports tab produces date-ranged billing reports (all customers, one customer, or one billing type) with CSV download, plus daily/weekly usage-trend charts. The System tab shows Zapier integration health and the current-period billing snapshot. Full procedures: ACCOUNTING.md.

4A. Customer portal

Your customers self-serve at http://localhost:3021/portal/ (access-web; loopback edge /portal remains on :3000): signup (or claiming an account you created, by email), sign-in with optional TOTP two-factor authentication, month-to-date usage, invoice history with print view, prepaid balance reloads (drawn down automatically at invoice issue), email-invoicing preferences, API-key regeneration, and live pricing. The full end-user guide is CUSTOMER-PORTAL.md.

5. Using the public API

All calls need the customer’s API key in the x-api-key header. Interactive docs with a “Try it out” console are at /docs.

# Free status check
curl -H 'x-api-key: key-ada' http://localhost:3000/v1/status

# Fixed-price call (4¢ list)
curl -X POST -H 'x-api-key: key-grace' -H 'content-type: application/json' \
  -d '{"text":"hello"}' http://localhost:3000/v1/transform

# Variable-price call: metadata + attachments
curl -X POST -H 'x-api-key: key-grace' \
  -F 'metadata={"title":"Q3 report"}' \
  -F 'attachments=@report.pdf' \
  http://localhost:3000/v1/storage

# List your stored items (free)
curl -H 'x-api-key: key-grace' http://localhost:3000/v1/storage

# Your month-to-date usage, with credit applied
curl -H 'x-api-key: key-grace' http://localhost:3000/v1/usage

Limits & validation: requests are validated against openapi.yaml (bad requests get 400); attachments are capped at 25 MB per file; metadata must be valid JSON (400 otherwise).

6. Billing operations (Stripe)

6.1 How it works

A scheduled job runs the billing reporter daily at 06:17 America/New_York (Kimi cron job “Zappier billing · report usage to Stripe”). For each customer with a Stripe ID it:

1. Sums their usage since the 1st of the month, subtracts their type’s monthly credit → billable cents.
2. Reports only the delta above what was already reported this month to Stripe as a meter event (zappier.api_cents, value = cents).
3. Records the new cumulative total in the billing_reports ledger.

Re-running is always safe: the ledger makes repeats no-ops, a per-run lock prevents overlapping executions, and a deterministic Stripe identifier (customer:period:billable) dedupes crash retries.

6.2 One-time Stripe setup (test mode)

1. Dashboard (test mode ON) → Billing → Meters → Create meter: event name zappier.api_cents, aggregation Sum of value, customer mapping stripe_customer_id.

2. Product catalog → Add product “Zappier API usage” → price: recurring, monthly, metered against that meter, $0.01 per unit (1 unit = 1 cent).

3. For each billable customer: create the Stripe Customer, attach a payment method, and add a subscription with the metered price. Meter events for customers without a metered subscription are recorded but never invoiced.

4. Put the sk_test_... key into .env (replace the placeholder).

5. Attach Stripe IDs to Zappier customers:

   curl -X PUT -H 'x-admin-key: admin-dev-key' -H 'content-type: application/json' \
     -d '{"stripeCustomerId":"cus_..."}' \
     http://localhost:3000/admin/api/customers/cust_2

6.3 Verifying a run

npx ts-node src/jobs/report-usage.ts

Expected output per customer:

• skip <id> <period> (nothing to report) — no billable usage yet
• skip <id> <period> (already reported Nc) — no new usage since last run
• <id>: reported N billable cents to Stripe — delta sent
• report-usage: another run holds the lock, abort run — safe concurrent abort

Then check the meter’s Events tab in the Stripe dashboard and the test customer’s upcoming invoice.

6.4 Going live

Repeat 6.2 steps 1–3 in live mode, replace .env with the sk_live_... key from the same Stripe account, and keep the same cron. The live product prod_Uxv9SAeIOZzyx1 (currently deactivated) can be reactivated or recreated.

7. The Zapier integration

The zapier-app/ directory contains the Zapier Platform app:

• Authentication: API key — the user pastes their API base URL (e.g. http://localhost:3000) and their key-... customer key; the connection is tested against /v1/status.
• Trigger “New Item”: polls GET /v1/storage for newly stored items.
• Action “Store Data”: calls POST /v1/storage with metadata and optional file attachments — billed per the rate card.

To publish: create a Zapier developer account, cd zapier-app && npm install && zapier login && zapier push, then share the app or submit it to the Zapier marketplace.

8. Day-to-day runbook

9. Troubleshooting