# mercury-journal-entry-prep

Drafts accrual and cash reclassification journal entries from Mercury transactions for a NetSuite import template (it posts nothing).

Skill by Mercury. Category: Documents.

## Install

Project (for this project only):

```sh
npx skills add mercurytechnologies/mercury-skills --skill mercury-journal-entry-prep
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add mercurytechnologies/mercury-skills --skill mercury-journal-entry-prep -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Warn

Installs: 3. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/mercurytechnologies/mercury-skills/mercury-journal-entry-prep)

## Source

[Open the source](https://github.com/mercurytechnologies/mercury-skills/tree/HEAD/skills/mercury-journal-entry-prep). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
name: mercury-journal-entry-prep
description: "Produce the Source Data + Calculation + Journal Entry block for an Accounts Payable accrual or cash-reclassification entry sourced from Mercury transactions, ready to paste into a NetSuite Journal Entry import template."
metadata:
  version: "1.0.0"
  category: agentic
  scopes: [accounts:read, transactions:read]
  requires: [mercury-shared]
---

# Mercury Journal Entry Prep

Pulls Mercury transaction detail for a target period and emits a Journal Entry (JE) workpaper draft in the standard three-block structure used in the close process — Source Data | Calculation | Journal Entry — ready to paste into a NetSuite JE import template.

Supports two entry types where the source data lives in Mercury:

- **`ap-accrual`** (Accounts Payable accrual) — outgoing payments in the period that don't yet have an invoice or receipt attached. The accrual recognizes the expense even though the invoice hasn't been received.
- **`cash-reclass`** — internal transfers and sweeps between Mercury accounts that need to be reclassified between cash sub-accounts on the General Ledger (GL).

> This skill produces only the Mercury-sourced data blocks. NetSuite import, approval routing, and posting stay in your finance close process and are handled by the user.

This skill is **read-only by default**. The optional Step 7 (memo-tagging accrued transactions so they aren't double-counted next month) is the only write, and only fires after explicit user confirmation.

## Parameters

| Parameter | Default | Description |
|-----------|---------|-------------|
| `entryType` | (required) | One of `ap-accrual`, `cash-reclass`. |
| `period` | Last closed month | Period for the JE, as `YYYY-MM`. |
| `accountFilter` | All accounts | Optional list of Mercury account IDs to scope to. |
| `glMappingPath` | `./gl-mapping.jsonl` | Path to a JSONL file mapping `mercuryCategory` to NetSuite GL account. See "GL mapping file" below. |
| `outputDir` | `~/Downloads` | Where to write the assembled workpaper Markdown. |

## GL Mapping File

The skill expects a JSONL file with one row per mapping. Each row:

```json
{"mercuryCategory": "Software", "glAccount": "60410", "department": "31000", "memo": "SaaS"}
{"mercuryCategory": "Travel",   "glAccount": "60520", "department": "22000", "memo": "Travel"}
{"mercuryCategory": "Cloud Services", "glAccount": "60420", "department": "31000", "memo": "Hosting"}
```

- `mercuryCategory` (required) — the Mercury category string exactly as it appears in `transactions.category`.
- `glAccount` (required) — NetSuite GL account number, as a string.
- `department` (optional) — cost center / department code. Falls through to a placeholder if not supplied.
- `memo` (optional) — memo prefix; otherwise the skill defaults to `"<entryType> accrual <period>"` style.

If the mapping file is missing, the skill emits placeholders (`[GL?]`, `[DEPT?]`) and a "needs mapping" call-out at the top of the workpaper.

## Execution Strategy

### Step 1: Anchor and resolve scope

```
1. Run `date +%Y-%m-%d` to get today's date.
2. IF period not provided:
       period = previous calendar month, format YYYY-MM
3. Compute:
   - periodStart = first day of period
   - periodEnd   = last day of period
4. Run `mercury accounts list --max-items -1 --format jsonl`.
   IF accountFilter provided: restrict to those IDs.
5. Load GL mapping file. IF missing, set glMapping = {} and continue with placeholders.
```

### Step 2: Fetch transactions

```
mercury transactions list \
  [--account-id <id> ...] \
  --start <periodStart> --end <periodEnd> \
  --status sent \
  --max-items -1 --format jsonl \
  --transform 'transactions.#.{id,amount,postedAt,createdAt,counterpartyName,category,mercuryCategory,note,kind,counterpartyId}'
```

Use `--status sent` here — JEs are based on what actually posted. Pending items get accrued the *following* month if still pending at period end.

### Step 3a: Build the source set — `ap-accrual`

```
candidates = transactions where amount < 0   # debits only

# Drop transactions that already have an attachment (invoice/receipt on file).
# Mercury's transaction-list output may not include attachment counts; if it
# doesn't, run `mercury transactions get --transaction-id <id> --format jsonl`
# per candidate and inspect `attachments`.
FOR EACH txn IN candidates:
    full = mercury transactions get --transaction-id <txn.id> --format jsonl
    IF len(full.attachments) > 0:
        skip
    ELSE:
        accrualSet.push(txn)

# Aggregate by counterparty + Mercury category so each unique (vendor, category)
# pair becomes one row in the JE.
groups = {}
FOR EACH txn IN accrualSet:
    key = (txn.counterpartyName, txn.category || "Uncategorized")
    groups[key].total += abs(txn.amount)
    groups[key].count += 1
    groups[key].txnIds.push(txn.id)
```

### Step 3b: Build the source set — `cash-reclass`

```
# Internal transfers show up with both legs in the period. Detect them by
# `kind == "internalTransfer"` if present, otherwise by counterparty being
# another Mercury account in the user's org.
internalAccountIds = set(accounts.id for accounts in (step 1 account list))

transferLegs = []
FOR EACH txn IN transactions:
    IF txn.kind == "internalTransfer":
        transferLegs.push(txn)
    ELIF txn.counterpartyId IN internalAccountIds:
        transferLegs.push(txn)

# Each transfer has two legs (one debit, one credit). Pair them by (amount, date).
pairs = pairLegsByAmountAndDate(transferLegs)
```

### Step 4: Map to GL accounts

```
FOR EACH group IN groups (ap-accrual) OR pair IN pairs (cash-reclass):
    mapping = glMapping[group.category] OR glMapping[pair.fromAccount]
    IF mapping found:
        group.glAccount = mapping.glAccount
        group.department = mapping.department || "[DEPT?]"
        group.memoPrefix = mapping.memo || "<entryType> <period>"
    ELSE:
        group.glAccount = "[GL?]"
        group.department = "[DEPT?]"
        group.memoPrefix = "<entryType> <period>"
        unmappedCategories.push(group.category)
```

### Step 5: Compose the workpaper

Save to `<outputDir>/mercury-je-<entryType>-<period>.md` and print to the conversation.

**ap-accrual layout:**

```markdown
# Journal Entry: AP Accrual — <period>

**Type:** AP Accrual
**Period:** <period>
**Prepared:** <today> by <user>

<!-- if any categories were unmapped, list them here as a fix-before-posting block -->

## Source Data

| Txn ID | Date | Counterparty | Mercury Category | Amount | Attachment? | Tickmark |
|--------|------|--------------|------------------|--------|-------------|----------|
| <id>   | ...  | ...          | ...              | ...    | none        | ✓        |

## Calculation

| # | Counterparty | Mercury Category | Txn Count | Total | GL Account | Dept | Tickmark |
|---|--------------|------------------|-----------|-------|------------|------|----------|
| 1 | ...          | ...              | ...       | $...  | <gl>       | <d>  | ^        |

## Journal Entry (NetSuite import format)

| Account | Debit | Credit | Department | Memo |
|---------|-------|--------|------------|------|
| <gl-expense>          | $<amount> |           | <dept> | <memoPrefix> — <vendor> |
| 21000 (AP Accrual)    |           | $<amount> | <dept> | <memoPrefix> — <vendor> |

**Total Debits:** $<sum>   **Total Credits:** $<sum>   **Difference:** $0.00 ✓

## Review Checklist

- [ ] Debits equal credits
- [ ] Period is correct (<period>)
- [ ] All GL accounts are valid (no `[GL?]` placeholders remain)
- [ ] Department / cost center coded
- [ ] Reversal flag set for next period
- [ ] Approver identified (route per your close process; Broker Dealer entries may need a dedicated approver)
```

**cash-reclass layout:** same three-block structure, but Source Data lists transfer legs (from-account, to-account, amount, date), Calculation pairs legs, and the JE has one row per pair debiting the destination cash GL sub-account and crediting the source.

### Step 6: Print the review checklist and stop

The skill never posts the JE — NetSuite import is the user's job. Print the workpaper path and tell the user it's ready to paste into the JE import template.

### Step 7 (optional, write): Tag accrued transactions

After the JE is posted in NetSuite, the user can re-run the skill with `--tag-accrued` to mark every transaction in the accrual set with a note so it doesn't get re-accrued next month.

```
Prompt: "Tag {N} accrued transactions with 'accrued <period>' in their note? (y/N)"

IF user confirms:
    FOR EACH txn IN accrualSet:
        mercury transactions update \
          --transaction-id <txn.id> \
          --note "accrued <period>"
```

Subsequent runs should filter out transactions whose `note` already contains `accrued <prior-period>` so reversing entries can be derived without double-counting. Follow `mercury-shared` write rules — one transaction at a time, surface errors verbatim, stop on 401/403.

## Example Output

```
Mercury JE Prep — ap-accrual, 2026-04

Loaded 3 accounts, 27 mappings from ./gl-mapping.jsonl.
Pulled 412 sent transactions in period (Mar 31 - Apr 30, 2026).
Filtered to 89 outgoing debits.
Checked attachments: 11 unattached -> accrual candidates.
Aggregated to 7 (counterparty, category) groups.

Unmapped categories needing review: ["Marketing Software"]

Source Data:
  Txn ID         Date        Counterparty             Category            Amount     Attached?
  a7c0...-3f1e   2026-04-12  NewTech Solutions        Software            -$18,500   none
  b8d1...-4f2e   2026-04-18  ToolCo                   Software             -$5,200   none
  ...

Calculation:
  # | Counterparty             | Category            | N | Total      | GL     | Dept   | TM
  1 | NewTech Solutions        | Software            | 1 | $18,500.00 | 60410  | 31000  | ^
  2 | ToolCo                   | Software            | 1 |  $5,200.00 | 60410  | 31000  | ^
  3 | Acme Cloud               | Cloud Services      | 2 | $12,450.00 | 60420  | 31000  | ^

Journal Entry:
  Account | Debit       | Credit      | Department | Memo
  60410   | $23,700.00  |             | 31000      | ap-accrual 2026-04 — Software
  60420   | $12,450.00  |             | 31000      | ap-accrual 2026-04 — Cloud Services
  ...
  21000   |             | $36,150.00  | 31000      | ap-accrual 2026-04

  Total Debits: $36,150.00   Total Credits: $36,150.00   Difference: $0.00 ✓

Saved workpaper: ~/Downloads/mercury-je-ap-accrual-2026-04.md
```

## Tips

- **Mapping file lives next to the data**, not committed to this repo. The canonical `mercuryCategory -> GL account` mapping is maintained by your finance team — copy it locally for each run, don't drift.
- **Unmapped categories block posting.** Print them in a top-of-file call-out so they get fixed before the JE leaves the workpaper.
- **Pending items belong to next month.** Don't accrue items that are still `status: pending` at period end — they'll post (with possibly different amounts) in the next period and get caught by next month's run.
- **Reversal flag** — most AP accruals are auto-reversing in the following period. The review checklist surfaces this so it's not missed.
- **`mercury transactions update` accepts `--note`**, not `--memo`. Don't typo this — it's the rule the autocategorize skill follows too.
- **Internal-transfer detection is heuristic.** If `kind == "internalTransfer"` isn't present in your CLI build, fall back to "counterparty is one of my own account IDs" — but verify the leg pairing on the first run since spurious pairs can occur on same-day same-amount external transfers.
````

- Previous: [mercury-detect-anomaly](https://syn4pse.dev/terminal/mercury-detect-anomaly.md)
- Next: [mercury-onboarding-apply](https://syn4pse.dev/terminal/mercury-onboarding-apply.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
