Bookkeeping

Vendor credits

Credit memos from vendors: apply them to open bills, or record the cash refund.

Create a vendor credit

Scope: vendor_credits:write. Each line names the account the credit reduces, usually the expense account the original bill used. The vendor is matched by name or created, like on bills.

A vendor credit posts when it is created, on its date: Accounts Payable is debited and each line's account is credited. There is no draft. To undo one, void it.

Send applications to apply the credit to the same vendor's open bills right away. Applications are checked before anything is saved; a bad one returns 422 invalid_application and creates nothing.

POST

curl -X POST "https://api.helloledger.ai/v1/companies/{company_id}/vendor-credits" \
  -H "Authorization: Bearer $HL_API_KEY" \
  -H "Idempotency-Key: vc_4410" \
  -H "Content-Type: application/json" \
  -d '{
  "vendor_id": "66f1a2b3c4d5e6f708092a01",
  "date": "2026-10-10",
  "credit_number": "CM-1182",
  "reason": "Returned damaged linens",
  "external_id": "vc_4410",
  "lines": [
    {
      "account_id": "66f1a2b3c4d5e6f708091d01",
      "description": "Linens returned",
      "amount": "100.00"
    }
  ],
  "applications": [
    {
      "bill_id": "66f1a2b3c4d5e6f708093b01",
      "amount": "40.00"
    }
  ]
}'

Response (201)

{
  "vendor_credit_id": "66f1a2b3c4d5e6f708097f01",
  "external_id": "vc_4410",
  "vendor_id": "66f1a2b3c4d5e6f708092a01",
  "vendor_name": "Staples",
  "credit_number": "CM-1182",
  "date": "2026-10-10",
  "status": "partial",
  "total_amount": "100.00",
  "amount_applied": "40.00",
  "refunded_amount": "0.00",
  "unapplied_amount": "60.00",
  "currency": "USD",
  "lines": [{ "account_id": "66f1a2b3c4d5e6f708091d01", "account_name": "Office Supplies", "description": "Linens returned", "amount": "100.00" }],
  "applications": [{ "bill_id": "66f1a2b3c4d5e6f708093b01", "amount": "40.00", "applied_at": "2026-10-10T15:04:05" }],
  "refunds": [],
  "result": "created"
}

Fields

Field	Notes
vendor_id or vendor	Required, one or the other. vendor takes the same fields as POST /vendors.
date	Credit date (YYYY-MM-DD). The ledger entry uses this date.
lines	1–100 lines of account_id and amount, with an optional description.
applications	Optional. Bills to apply the credit to now: bill_id and amount.
credit_number, reason, memo	Optional.
ap_account_id	Accounts Payable account. Defaults to the company's A/P account.
external_id	Your ID for the credit, stored for reference.

Status

Status	Meaning
open	Nothing applied or refunded yet.
partial	Some of the credit is applied or refunded.
applied	The whole credit is applied or refunded.
voided	Reversed. Kept for the audit trail.

Apply the unapplied balance to the vendor's open bills. Each amount can't exceed the bill's balance, and the total can't exceed the credit's unapplied amount (422 exceeds_unapplied). The bill's amount_credited and balance_due update.

POST

curl -X POST "https://api.helloledger.ai/v1/companies/{company_id}/vendor-credits/66f1a2b3c4d5e6f708097f01/apply" \
  -H "Authorization: Bearer $HL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "applications": [
    {
      "bill_id": "66f1a2b3c4d5e6f708093b01",
      "amount": "60.00"
    }
  ]
}'

Record a refund

When the vendor pays the credit back instead, record the refund into the bank or cash account it landed in. The bank account is debited and Accounts Payable is credited. Send an Idempotency-Key so a retry doesn't record it twice.

POST

curl -X POST "https://api.helloledger.ai/v1/companies/{company_id}/vendor-credits/66f1a2b3c4d5e6f708097f01/refund" \
  -H "Authorization: Bearer $HL_API_KEY" \
  -H "Idempotency-Key: vc_4410_refund_1" \
  -H "Content-Type: application/json" \
  -d '{
  "date": "2026-10-20",
  "amount": "60.00",
  "deposit_account_id": "66f1a2b3c4d5e6f708091d03",
  "memo": "Check 2231"
}'

List and read vendor credits

Scope: vendor_credits:read or vendor_credits:write. Filter by vendor_id, status, external_id, and a from/to date range. Credits entered in HelloLedger are listed too.

GET

curl "https://api.helloledger.ai/v1/companies/{company_id}/vendor-credits?status=open&limit=50" \
  -H "Authorization: Bearer $HL_API_KEY"

One credit · GET

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

Void a vendor credit

Voiding removes the credit's ledger entries and takes it off any bills it was applied to. A credit with a refund returns 409 credit_has_refunds; reverse the refund in HelloLedger first.

POST

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

Create a vendor credit

Fields

Status

Apply to bills

Record a refund

List and read vendor credits

Void a vendor credit