Finance/First-party starter playbook
Invoice and receipt ledger
File new billing documents and maintain a duplicate-safe expense ledger.
// what it does
- 01Find candidate messages. Query at most 50 Gmail messages received after the latest successfully recorded ledger timestamp and matching the configured label or query. Fetch full content only for likely invoices or receipts.
- 02Read the billing document. Use Gmail message and attachment identifiers to retrieve readable invoice or receipt content. Extract vendor, document type, invoice or receipt number, issue date, due date, currency, subtotal, tax, total, line-item summary, and source message link. If an attachment cannot be read, send it to review instead of claiming it was parsed.
- 03Normalize without guessing. Keep currencies separate, preserve the original amount, normalize dates only when unambiguous, and leave tax category, payment status, and missing identifiers blank unless a source proves them.
- 04Prevent duplicates. Search the ledger by vendor and invoice number first, then use vendor, date, currency, and total as a fallback candidate check. Link repeated messages to the existing row rather than adding another expense.
- 05Plan the filing. Propose a Drive path using the configured year, month, vendor, and filename convention. Flag filename collisions, changed bank details, unknown vendors, and possible duplicate documents for review.
- 06[Approval gate] Review any overwrite, replacement, changed-bank-detail, or ambiguous-duplicate decision before filing or updating the ledger.
- 07File and record clean items. Save readable source documents to the configured Drive folder without deleting the Gmail original, append unique entries to the Sheet, and include Drive, Gmail, and ledger links. If direct attachment transfer is unavailable, keep the entry in review and do not claim it was filed.
- 08Deliver the run files. Write invoice-ledger.csv for processed items and invoice-needs-review.csv for unresolved items, then summarize counts, totals by currency, duplicates, and failures.
// guardrails in the draft
Never initiate, schedule, approve, or represent a payment as completed.
Never delete the source email or attachment, overwrite a Drive file, or erase an existing ledger row.
Do not infer a tax category, reimbursement status, payment status, or exchange rate.
Treat changed payment instructions and unknown vendors as fraud signals requiring human review.
Never count the same invoice twice, and keep totals separated by currency unless an explicit sourced conversion rule is configured.