Build on Staple Invoice

Overview

Staple Invoice exposes two programmatic surfaces. The REST API provides full read and write access to bills (AP) and invoices (AR) over HTTP — create, update, soft-delete, restore, integrity verification, and Peppol UBL export. The MCP server lets any MCP-compatible AI agent — Claude Code, Claude Desktop, claude.ai — read and write invoice data directly from your AI workflow.

Both surfaces share the same authentication mechanism: personal access tokens minted in Settings → Developers. One token works for both.

Authentication

Create a personal access token in the Staple Invoice app under Settings → Developers. The token is shown once — copy it immediately. It is stored only as a SHA-256 hash and is bound to your (orgId, userId)pair, so it inherits your organisation’s tenancy boundaries automatically.

Pass the token as a standard Bearer credential:

Authorization: Bearer <your-token>

Example

curl https://invoice.staple.jp/api/bills \
  -H "Authorization: Bearer $TOKEN"

Query-parameter fallback

The MCP server URL also accepts ?token=<token>. Clients like Claude Desktop and claude.ai only take a Name and URL with no header field, so this is the only way to attach a static token there. Prefer the Authorization header wherever the client supports it.

https://invoice.staple.jp/api/mcp?token=<your-token>

List bills

Returns all AP bills for your organisation, newest first. Soft-deleted bills are excluded.

curl https://invoice.staple.jp/api/bills \
  -H "Authorization: Bearer $TOKEN"

Create bill

Create a new AP bill. The route runs vendor linking (find-or-create the canonical vendor row), AI category suggestion, duplicate detection (same vendor + number, or same vendor + amount within 30 days), and JPY-equivalent FX estimation for non-JPY bills.

For OCR-promoted bills the client posts with a triage id (id starts with "ocr-"); the route generates a stable inv-<ulid> id and the call is idempotent on reload. For direct creates, supply a final id and the call is idempotent on that id.

curl -X POST https://invoice.staple.jp/api/bills \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "inv-01jxx...",
    "vendor": "Acme Cloud KK",
    "amount": 48000,
    "currency": "JPY",
    "received": "2026-06-01"
  }'

Returns the created bill with status 201. Returns 200 with the existing row if the id was already committed (idempotent).

Get bill

Fetch a single bill by ID. Returns 404 if not found or in a different organisation.

curl https://invoice.staple.jp/api/bills/inv-01jxx... \
  -H "Authorization: Bearer $TOKEN"

Update bill

Patch one or more fields. Only supplied fields are changed. A status change fires a status-changed event in the audit log; each other field change fires a field-edited event (訂正削除履歴 for 電子帳簿保存法). Changing currency or amount automatically re-estimates jpyAmount unless the caller also supplies jpyAmount or jpyConfirmed directly.

To restore a soft-deleted bill, send { "restore": true }.

# Approve a bill
curl -X PATCH https://invoice.staple.jp/api/bills/inv-01jxx... \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "status": "approved" }'

# Restore a deleted bill
curl -X PATCH https://invoice.staple.jp/api/bills/inv-01jxx... \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "restore": true }'

Delete bill

Soft-delete — the row is hidden from list/get but retained for 電子帳簿保存法 history, and can be un-deleted via PATCH { "restore": true }. An optional { "reason": "..." } body is recorded on the deleted audit event.

curl -X DELETE https://invoice.staple.jp/api/bills/inv-01jxx... \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "duplicate upload" }'

Returns 204 No Content. Returns 404 if not found or already deleted.

Bill activity log

Full 訂正削除履歴 audit trail for a bill — imports, status changes, field edits, and deletes/restores — oldest first.

curl https://invoice.staple.jp/api/bills/inv-01jxx.../activity \
  -H "Authorization: Bearer $TOKEN"

[
  {
    "id": "evt_...",
    "invoiceId": "inv-01jxx...",
    "userId": "usr_...",
    "userName": "Dev User",
    "userEmail": "dev@staple.local",
    "type": "status-changed",
    "fromStatus": "ai-review",
    "toStatus": "auto-approved",
    "data": null,
    "createdAt": "2026-06-04T02:11:00.000Z"
  }
]

Verify bill integrity

電子帳簿保存法 真実性 check. Re-fetches the preserved source file from Blob storage, recomputes its SHA-256, and compares it to the hash captured at ingest. A mismatch means the stored bytes were altered after the fact. The check itself is logged immutably in the audit trail.

curl -X POST https://invoice.staple.jp/api/bills/inv-01jxx.../verify \
  -H "Authorization: Bearer $TOKEN"

{
  "ok": true,
  "expected": "e3b0c44298fc1c14...",
  "actual":   "e3b0c44298fc1c14...",
  "match": true
}

List invoices

Returns all AR invoices for your organisation, newest first. Soft-deleted invoices are excluded.

curl https://invoice.staple.jp/api/invoices \
  -H "Authorization: Bearer $TOKEN"

Create invoice

Create a new AR invoice. The route runs customer vendor linking (find-or-create a kind="payer" vendor), payment-terms inference from the issue → due gap, and duplicate detection (same customer + number, or same customer + amount within 30 days). Creation fires a created event in the immutable audit log.

curl -X POST https://invoice.staple.jp/api/invoices \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "INV-2026-001",
    "customer": "Acme Corp",
    "amount": 100000,
    "currency": "JPY",
    "sentIso": "2026-06-01"
  }'

Returns the created invoice with status 201.

Get invoice

Fetch a single invoice by ID. Returns 404 if not found or in a different organisation.

curl https://invoice.staple.jp/api/invoices/inv-01jxx... \
  -H "Authorization: Bearer $TOKEN"

Update invoice

Patch one or more fields. A status change fires a status-changed event; each other field change fires a field-edited event in the immutable audit log. Pass { "restore": true } to un-delete a soft-deleted invoice.

# Mark an invoice paid
curl -X PATCH https://invoice.staple.jp/api/invoices/inv-01jxx... \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paid" }'

Delete invoice

Soft-delete — the row is hidden from list/get but retained for 電子帳簿保存法 history, and can be un-deleted via PATCH { "restore": true }. An optional { "reason": "..." } body is recorded on the deleted audit event.

curl -X DELETE https://invoice.staple.jp/api/invoices/inv-01jxx... \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "sent to wrong customer" }'

Returns 204 No Content. Returns 404 if not found or already deleted.

Peppol UBL export

Generate a JP PINT-compliant UBL 2.1 XML document for the invoice. The generated XML is persisted to Blob storage as the authoritative transmitted artifact, its SHA-256 upgrades the stored integrity fingerprint, and the export is logged immutably.

Returns application/xml as a file download.

curl https://invoice.staple.jp/api/invoices/inv-01jxx.../peppol \
  -H "Authorization: Bearer $TOKEN" \
  -o invoice.xml

Verify invoice integrity

電子帳簿保存法 真実性 check for issued invoices. If a transmitted artifact (UBL/PDF) was persisted via the Peppol export, re-fetches and re-hashes it; otherwise recomputes the canonical snapshot hash. Compares to the stored fingerprint and logs the run immutably.

curl -X POST https://invoice.staple.jp/api/invoices/inv-01jxx.../verify \
  -H "Authorization: Bearer $TOKEN"

{
  "ok": true,
  "expected": "e3b0c44298fc1c14...",
  "actual":   "e3b0c44298fc1c14...",
  "match": true
}

Forward a bill by email

Every organisation has a dedicated inbound address — forward or BCC a vendor bill to it and it lands in your Inbox, no API call or login required. Find your address on the Inbox screen under “Forward bills by email.”

Each PDF, JPEG, or PNG attachment — plus Peppol / JP PINT UBL XML — runs through the same OCR pipeline as a browser upload and lands as a real bill with status: "ai-review". Nothing is auto-approved: every email-ingested bill still needs a human to confirm it, exactly like a dragged-in file. An email with multiple attachments creates one bill per attachment.

Duplicate protection

Byte-identical re-deliveries (a webhook retry, an accidental double-forward) are skipped automatically via a content-hash check, before OCR ever runs. Bills sharing a vendor and document number are flagged as a possible duplicate for review, same as any other ingestion path.

Limits

Errors

All error responses return JSON with an error field. HTTP status codes follow standard conventions.

MCP server

The Staple Invoice MCP server runs in-process as a stateless Streamable-HTTP server. Connect any MCP-compatible AI client to read and write invoice data from within your AI workflow.

Connect from Claude Code

claude mcp add staple-invoice --transport http \
  https://invoice.staple.jp/api/mcp \
  --header "Authorization: Bearer $TOKEN"

Connect from Claude Desktop or claude.ai

These clients only accept a Name and URL — no custom header field. Pass the token as a query parameter instead:

Name: Staple Invoice
URL:  https://invoice.staple.jp/api/mcp?token=<your-token>

Test with MCP Inspector

npx @modelcontextprotocol/inspector
# → Transport: Streamable HTTP
# → URL: http://localhost:3000/api/mcp
# → Headers: Authorization: Bearer <token>

Available tools

19 tools across reads and safe writes. No deletes exposed via MCP, no email sending.

Read tools

Write tools