Bookkeeping

Card credits

Money a card gave back: merchant refunds and statement credits such as cashback or a won dispute.

Two kinds

kind	Use it for	Lines usually credit
refund	A merchant refunded a charge (returned goods, cancelled booking).	The expense account the original charge used.
statement_credit	The issuer credited the card: cashback, rewards, a won dispute, a goodwill credit.	An other-income account for rewards, or the expense account for a dispute.

Create a card credit

Scope: expenses:write. card_account_id is the credit card (or bank, for a debit card) account the credit landed on. The merchant is optional and is matched by name or created.

With "post": true the credit posts right away: the card account is debited (its balance goes down) and each line's account is credited. Without it the credit is saved as a draft.

POST

curl -X POST "https://api.helloledger.ai/v1/companies/{company_id}/card-credits" \
  -H "Authorization: Bearer $HL_API_KEY" \
  -H "Idempotency-Key: cc_7781" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "refund",
  "date": "2026-10-12",
  "card_account_id": "66f1a2b3c4d5e6f708091d04",
  "vendor": {
    "name": "Amazon"
  },
  "reference": "AMZ-RET-5531",
  "external_id": "cc_7781",
  "post": true,
  "lines": [
    {
      "account_id": "66f1a2b3c4d5e6f708091d01",
      "description": "Returned towels",
      "amount": "55.00"
    }
  ]
}'

Cashback · POST

curl -X POST "https://api.helloledger.ai/v1/companies/{company_id}/card-credits" \
  -H "Authorization: Bearer $HL_API_KEY" \
  -H "Idempotency-Key: cc_7782" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "statement_credit",
  "date": "2026-10-28",
  "card_account_id": "66f1a2b3c4d5e6f708091d04",
  "memo": "Q3 cashback",
  "post": true,
  "lines": [
    {
      "account_id": "66f1a2b3c4d5e6f708091d06",
      "amount": "25.00"
    }
  ]
}'

Response (201)

{
  "card_credit_id": "66f1a2b3c4d5e6f708098a01",
  "external_id": "cc_7781",
  "kind": "refund",
  "date": "2026-10-12",
  "status": "posted",
  "posted": true,
  "card_account_id": "66f1a2b3c4d5e6f708091d04",
  "card_account_name": "Company Card",
  "vendor_name": "Amazon",
  "vendor_created": false,
  "reference": "AMZ-RET-5531",
  "total_amount": "55.00",
  "currency": "USD",
  "lines": [{ "account_id": "66f1a2b3c4d5e6f708091d01", "account_name": "Office Supplies", "description": "Returned towels", "amount": "55.00" }],
  "result": "created"
}

Fields

Field	Notes
kind	refund or statement_credit. Required on create.
date	Date the credit posted to the card (YYYY-MM-DD). Required on create.
card_account_id	Required on create. A credit card or bank account; other types return 422 invalid_card_account.
lines	1–100 lines of account_id and amount, with an optional description.
vendor_id or vendor	Optional, one or the other.
expense_id	Optional. The expense a refund reverses, for reference.
reference, memo, external_id	Optional.
post	true posts now. Default false saves a draft.

If the card feed also imports the credit

Card credits post to the ledger directly. If the same credit also arrives through a connected card feed, exclude that feed line in HelloLedger so the credit isn't counted twice. Card credits are listed through the API and show in the ledger and reports.

List and read card credits

Scope: expenses:read or expenses:write. Filter by kind, status (draft, posted, voided), card_account_id, external_id, and a from/to date range.

GET

curl "https://api.helloledger.ai/v1/companies/{company_id}/card-credits?kind=statement_credit&from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer $HL_API_KEY"

One credit · GET

curl "https://api.helloledger.ai/v1/companies/{company_id}/card-credits/66f1a2b3c4d5e6f708098a01" \
  -H "Authorization: Bearer $HL_API_KEY"

Edit, post, void, or delete

PATCH changes a draft or a posted credit; a posted one is re-posted with the new amounts. Voiding removes it from the ledger and keeps it with status voided. DELETE removes drafts only.

PATCH

curl -X PATCH "https://api.helloledger.ai/v1/companies/{company_id}/card-credits/66f1a2b3c4d5e6f708098a01" \
  -H "Authorization: Bearer $HL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "lines": [
    {
      "account_id": "66f1a2b3c4d5e6f708091d01",
      "description": "Returned towels",
      "amount": "60.00"
    }
  ]
}'

Post a draft · POST

curl -X POST "https://api.helloledger.ai/v1/companies/{company_id}/card-credits/66f1a2b3c4d5e6f708098a01/post" \
  -H "Authorization: Bearer $HL_API_KEY"

POST

curl -X POST "https://api.helloledger.ai/v1/companies/{company_id}/card-credits/66f1a2b3c4d5e6f708098a01/void" \
  -H "Authorization: Bearer $HL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Duplicate"
}'

Delete a draft · DELETE

curl -X DELETE "https://api.helloledger.ai/v1/companies/{company_id}/card-credits/66f1a2b3c4d5e6f708098a01" \
  -H "Authorization: Bearer $HL_API_KEY"