Transactions

UNCATEGORIZED ──PUT /coding──> CATEGORIZED ──POST /approve──> APPROVED
      ^                            │  ^                          │
      └────── DELETE /coding ──────┘  └──── POST /unapprove ─────┘

• UNCATEGORIZED: no journal entry. Grain’s rules and AI may add a suggestion.
• CATEGORIZED: a draft journal entry exists. It does not affect reports until approved.
• APPROVED: the journal entry is posted to the ledger.

​

Look up coding IDs

​

Create a transaction without duplicates

curl --fail-with-body "https://api.grainledger.com/api/v1/transactions" \
  -H "Authorization: Bearer $GRAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: card-txn-8812" \
  --data '{"description":"Office Depot","amount":184.32,"date":"2026-07-01","transactionType":"WITHDRAWAL","accountId":"YOUR_CARD_ACCOUNT_ID","externalId":"card-txn-8812"}'

• A retry with the same key and body returns 201 with the original transaction. A different body returns 409.
• A second transaction with the same externalId returns 409, even with a new key. Find the existing one with GET /api/v1/transactions?externalId=card-txn-8812.
• amount is always positive. DEPOSIT records money in; WITHDRAWAL, TRANSFER, and ADJUSTMENT record money out. The response’s direction is INFLOW or OUTFLOW.
• accountId is the ledger cash, bank, or card account the transaction clears through. Transactions from a connected feed use bankAccountId instead.

​

Code or split a transaction

curl --fail-with-body -X PUT "https://api.grainledger.com/api/v1/transactions/TXN_ID/coding" \
  -H "Authorization: Bearer $GRAIN_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "defaultFundId": "GENERAL_FUND_ID",
    "lines": [
      { "accountId": "SUPPLIES_ID", "amount": 120, "dimensions": [{ "dimensionId": "DEPT_ID", "dimensionValueId": "ADMIN_ID" }] },
      { "accountId": "HOSPITALITY_ID", "fundId": "YOUTH_FUND_ID", "amount": 64.32, "memo": "Volunteer lunch" }
    ]
  }'

• One line codes the transaction to a single account. Several lines split it across accounts, funds, or dimensions.
• A line’s fund falls back to defaultFundId, then to the transaction’s fund, then to the organization’s default fund.
• A line without dimensions inherits the transaction’s dimensions.
• Positive amounts allocate the transaction. A negative amount offsets another line, for example a refund inside a split. Response coding.lines use the same convention.
• Recoding is allowed until the transaction is approved. Unapprove first to change approved coding. Reconciled transactions cannot be recoded, and transactions in an open reconciliation return 409.

​

Set dimensions

​

Approve

• Approval fails if coding.missingRequiredDimensions is not empty (400) or the accounting period is locked.
• Approving an approved transaction returns it unchanged, so retries are safe. POST /unapprove works the same way in reverse.

​

Receipts

curl --fail-with-body "https://api.grainledger.com/api/v1/transactions/TXN_ID/attachments" \
  -H "Authorization: Bearer $GRAIN_API_KEY" \
  -F "file=@receipt.pdf;type=application/pdf"

• GET /transactions/{id}/attachments lists attachments, including receipts synced from card platforms.
• GET /transactions/{id}/attachments/{fileId}/download returns a signed URL that expires in 15 minutes. Request a new one each time you need the file; don’t store it.
• DELETE /transactions/{id}/attachments/{fileId} removes an attachment.

​

Changes in API version 1.3.0