SocialHz Engineering · 30 October 2026 · Requested by a customer
A credit ledger you can reconcile
GET /api/v1/credits · GET /api/v1/credits/history · GET /api/v1/credits/statement
What shipped
A workspace now has one credit balance, shared by every platform, and every change to it is a row in a ledger: a charge, a refund or a top-up. The same ledger is behind the Credits page in the app.
Why
Customers reconciling their spend wanted to match each charge to the call that made it, line by line, without asking us.
A ledger row
GET /api/v1/credits/history
{ "at": "2026-11-02T10:14:07Z", "kind": "charge", "platform": "instagram-search",
"ref": "3f9c2a71b8e04d55", "label": "Search",
"quantity": 3, "unit_price": 1, "credits": -3, "balance": 97 }Tracing a charge
- ref on a search charge is the request_id from that search's answer, so any charge can be matched to its call.
- quantity × unit_price = credits. A platform with its own page price, like LinkedIn at 5 credits a page, shows it here.
- A refund is booked against the day of the charge it reverses, not the day it happened, so daily totals stay true.
- Pages that fail, and searches that fail, are refunded automatically and show as their own rows.
Balance and statement
GET /api/v1/credits gives the balance left. GET /api/v1/credits/statement totals a period: opening, added, adjusted, charged, refunded and the balance, with a breakdown per platform.
Request a feature
Tell us what you need on the updates page. The engineering team reads every request.