Credit cards

Record charges, payments, refunds and interest on a credit card as a liability account, and know what the sign of its balance means.

A credit card is money you owe, so it belongs in a liability account of type CREDIT, not in your assets. Every charge makes the debt larger; every payment makes it smaller. Keeping the card as an account of its own lets you see what you owe at any moment and reconcile it against each monthly statement.

Signs

A CREDIT account has a credit balance when you owe money, which is a negative number in the book's raw sign. A charge is a credit to the card (-) and a debit to the expense (+). A payment is the reverse: a debit to the card (+) and a credit to the bank (-). So a balance of -185.00 means you owe 185.00.

Steps

Create the card account with account.create, type CREDIT, in the card's currency. Create an expense account for the interest the card charges.
Record each charge with transaction.post: the expense +, the card -.
Record a refund as the opposite of a charge: the card +, the expense -.
Record interest and fees from the statement: the interest expense +, the card -.
Record a payment: the card +, the bank account -.
Check what you owe with account.balance.
Reconcile against the statement as in Reconcile an account, with the statement's ending balance given in the card's raw sign (negative for money owed).

Example

Example: with a new, empty book open as book.gnucash, at 2024-07-31T12:00:00Z.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Checking","type":"BANK","commodity":"USD"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "…"
}

Request:

{"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Visa","type":"CREDIT","commodity":"USD"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": "…"
}

Request:

{"jsonrpc":"2.0","id":3,"method":"account.create","params":{"name":"Groceries","type":"EXPENSE","commodity":"USD"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": "…"
}

Request:

{"jsonrpc":"2.0","id":4,"method":"account.create","params":{"name":"Card interest","type":"EXPENSE","commodity":"USD"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": "…"
}

Request:

{"jsonrpc":"2.0","id":5,"method":"transaction.post","params":{"datePosted":"2024-07-03","description":"Supermarket","splits":[{"account":"Groceries","value":"120.00"},{"account":"Visa","value":"-120.00"}]}}

Response:

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "balanced": true,
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":6,"method":"transaction.post","params":{"datePosted":"2024-07-10","description":"Supermarket","splits":[{"account":"Groceries","value":"80.00"},{"account":"Visa","value":"-80.00"}]}}

Response:

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "balanced": true,
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":7,"method":"transaction.post","params":{"datePosted":"2024-07-12","description":"Returned goods","splits":[{"account":"Visa","value":"30.00"},{"account":"Groceries","value":"-30.00"}]}}

Response:

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "balanced": true,
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":8,"method":"transaction.post","params":{"datePosted":"2024-07-20","description":"Interest","splits":[{"account":"Card interest","value":"15.00"},{"account":"Visa","value":"-15.00"}]}}

Response:

{
  "jsonrpc": "2.0",
  "id": 8,
  "result": {
    "balanced": true,
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":9,"method":"account.balance","params":{"account":"Visa"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 9,
  "result": {
    "balances": {
      "commodity": "CURRENCY::USD",
      "balance": {
        "num": "-18500",
        "denom": "100"
      },
      "…": "…"
    },
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":10,"method":"transaction.post","params":{"datePosted":"2024-07-25","description":"Card payment","splits":[{"account":"Visa","value":"100.00"},{"account":"Checking","value":"-100.00"}]}}

Response:

{
  "jsonrpc": "2.0",
  "id": 10,
  "result": {
    "balanced": true,
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":11,"method":"account.balance","params":{"account":"Visa"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 11,
  "result": {
    "balances": {
      "balance": {
        "num": "-8500",
        "denom": "100"
      },
      "…": "…"
    },
    "…": "…"
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
account.create {"name":"Checking","type":"BANK","commodity":"USD"}
account.create {"name":"Visa","type":"CREDIT","commodity":"USD"}
account.create {"name":"Groceries","type":"EXPENSE","commodity":"USD"}
account.create {"name":"Card interest","type":"EXPENSE","commodity":"USD"}
transaction.post {"datePosted":"2024-07-03","description":"Supermarket","splits":[{"account":"Groceries","value":"120.00"},{"account":"Visa","value":"-120.00"}]}
transaction.post {"datePosted":"2024-07-10","description":"Supermarket","splits":[{"account":"Groceries","value":"80.00"},{"account":"Visa","value":"-80.00"}]}
transaction.post {"datePosted":"2024-07-12","description":"Returned goods","splits":[{"account":"Visa","value":"30.00"},{"account":"Groceries","value":"-30.00"}]}
transaction.post {"datePosted":"2024-07-20","description":"Interest","splits":[{"account":"Card interest","value":"15.00"},{"account":"Visa","value":"-15.00"}]}
account.balance {"account":"Visa"}
transaction.post {"datePosted":"2024-07-25","description":"Card payment","splits":[{"account":"Visa","value":"100.00"},{"account":"Checking","value":"-100.00"}]}
account.balance {"account":"Visa"}
EOF

It prints:

[
  "…",
  "…",
  "…",
  "…",
  {
    "balanced": true,
    "…": "…"
  },
  {
    "balanced": true,
    "…": "…"
  },
  {
    "balanced": true,
    "…": "…"
  },
  {
    "balanced": true,
    "…": "…"
  },
  {
    "balances": {
      "commodity": "CURRENCY::USD",
      "balance": {
        "num": "-18500",
        "denom": "100"
      },
      "…": "…"
    },
    "…": "…"
  },
  {
    "balanced": true,
    "…": "…"
  },
  {
    "balances": {
      "balance": {
        "num": "-8500",
        "denom": "100"
      },
      "…": "…"
    },
    "…": "…"
  }
]

MCP tool call

Tool call:

{"name":"account.create","arguments":{"name":"Checking","type":"BANK","commodity":"USD"}}

Result:

{
  "content": [
    {
      "type": "text",
      "text": "\"…\""
    }
  ]
}

Tool call:

{"name":"account.create","arguments":{"name":"Visa","type":"CREDIT","commodity":"USD"}}

Result:

{
  "content": [
    {
      "type": "text",
      "text": "\"…\""
    }
  ]
}

Tool call:

{"name":"account.create","arguments":{"name":"Groceries","type":"EXPENSE","commodity":"USD"}}

Result:

{
  "content": [
    {
      "type": "text",
      "text": "\"…\""
    }
  ]
}

Tool call:

{"name":"account.create","arguments":{"name":"Card interest","type":"EXPENSE","commodity":"USD"}}

Result:

{
  "content": [
    {
      "type": "text",
      "text": "\"…\""
    }
  ]
}

Tool call:

{"name":"transaction.post","arguments":{"datePosted":"2024-07-03","description":"Supermarket","splits":[{"account":"Groceries","value":"120.00"},{"account":"Visa","value":"-120.00"}]}}

Result:

{
  "structuredContent": {
    "balanced": true,
    "…": "…"
  }
}

Tool call:

{"name":"transaction.post","arguments":{"datePosted":"2024-07-10","description":"Supermarket","splits":[{"account":"Groceries","value":"80.00"},{"account":"Visa","value":"-80.00"}]}}

Result:

{
  "structuredContent": {
    "balanced": true,
    "…": "…"
  }
}

Tool call:

{"name":"transaction.post","arguments":{"datePosted":"2024-07-12","description":"Returned goods","splits":[{"account":"Visa","value":"30.00"},{"account":"Groceries","value":"-30.00"}]}}

Result:

{
  "structuredContent": {
    "balanced": true,
    "…": "…"
  }
}

Tool call:

{"name":"transaction.post","arguments":{"datePosted":"2024-07-20","description":"Interest","splits":[{"account":"Card interest","value":"15.00"},{"account":"Visa","value":"-15.00"}]}}

Result:

{
  "structuredContent": {
    "balanced": true,
    "…": "…"
  }
}

Tool call:

{"name":"account.balance","arguments":{"account":"Visa"}}

Result:

{
  "structuredContent": {
    "balances": {
      "commodity": "CURRENCY::USD",
      "balance": {
        "num": "-18500",
        "denom": "100"
      },
      "…": "…"
    },
    "…": "…"
  }
}

Tool call:

{"name":"transaction.post","arguments":{"datePosted":"2024-07-25","description":"Card payment","splits":[{"account":"Visa","value":"100.00"},{"account":"Checking","value":"-100.00"}]}}

Result:

{
  "structuredContent": {
    "balanced": true,
    "…": "…"
  }
}

Tool call:

{"name":"account.balance","arguments":{"account":"Visa"}}

Result:

{
  "structuredContent": {
    "balances": {
      "balance": {
        "num": "-8500",
        "denom": "100"
      },
      "…": "…"
    },
    "…": "…"
  }
}