Store credit

Every store-credit account with its balance, which is summed from the account's transactions on every read and stored in no column anywhere. One account per customer, plus an anonymous account per order that issued a gift card — a guest can buy a card, and a guest has no customer record to hang one on. Pass customer_id to narrow to one person.

One account with its balance, the customer it belongs to, and how many movements it carries.

One account's movements, newest first, each with the provenance the ledger required of it — what produced the row (gift_card, refund, order or adjustment), which one, the order it belongs to, and a source snapshot of what the producing rule saw. This is how you answer "why is this balance what it is?". Positive amounts credit the account and negative amounts debit it.

Add credit to an account or take some back, by hand. The amount is signed — positive credits, negative debits — and a note is required, because this is the only movement in the whole ledger a person makes rather than a rule, and it is the one row nobody will be able to explain later without one. A debit larger than the balance is refused before anything is written. Send amount as a decimal string or amount_minor in minor units.

Give a refund back as store credit instead of to the card that paid for the order. The same refund in every other way — it counts against the same refundable balance, restocks the same lines, fires the same events, earns the same credit note and sends the same email. A split refund needs no special call: refund part of the order through refund_order for the card's share and the rest through this one. Omit items to refund whatever is left of the order.

The numbered documents an order's refunds have earned, oldest first. A credit note is issued automatically whenever a refund is confirmed, is numbered from its own gapless sequence, and states the tax being credited. The PDF is not available through this interface — it is a document to print rather than a payload to read.