Billing
list_credit_transactions
readList credit transactions
Explain where the Store AI credits went, or when credits were added, after get_store_billing reports the balance.
Overview
Lists the AI credit history of the connected Store, newest first, as the merchant admin AI credits page shows it: each entry id, whether it added credits (credit) or spent or removed them (debit), the balance it changed (plan or purchased credits), the merchant admin text, the signed number of credits and when it was recorded. It requires the billing:read scope and has no side effects.
Permission
Requires thebilling:readpermission. A connection without it answersinsufficient_scopenaming the permission to approve.
Annotations
Prerequisites
- A merchant has connected this store and approved the billing:read scope.
Arguments
How many entries to return per page, between 1 and 100. Defaults to 20.
The opaque next_cursor value from the previous page.
Result
Up to `limit` credit entries, newest first, plus the cursor for the next page.
The page of credit entries, newest first.
One of: credit, debit
One of: plan, purchased
The text the merchant admin shows. Do not parse it.
Credits changed; negative for a debit.
Error cases
The connection was approved without billing:read.
The cursor was altered or reused for a different collection or Store; restart with no cursor.
limit is not an integer from 1 to 100.
The two latest credit entries
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_credit_transactions",
"arguments": {
"limit": 2
}
}
}{
"jsonrpc": "2.0",
"id": 1,
"result": {
"structuredContent": {
"request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
"store": {
"id": 12,
"name": "Demo Signs"
},
"transactions": [
{
"id": 9021,
"type": "debit",
"bucket": "plan",
"description": "AI sign design",
"amount": -1,
"created_at": "2026-11-14T09:30:00Z"
},
{
"id": 9017,
"type": "credit",
"bucket": "purchased",
"description": "Purchased 100 credits",
"amount": 100,
"created_at": "2026-11-10T02:00:00Z"
}
],
"pagination": {
"has_more": true,
"next_cursor": "eyJ2IjoxfQ"
}
}
}
}A cursor from another collection (error)
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_credit_transactions",
"arguments": {
"cursor": "eyJ2IjoxfQ"
}
}
}{
"jsonrpc": "2.0",
"id": 1,
"result": {
"isError": true,
"structuredContent": {
"error": {
"code": "invalid_cursor",
"title": "Invalid cursor",
"detail": "The cursor is invalid, expired, or belongs to a different query.",
"recovery": "Cursors are opaque and are only valid for the filters they were issued with. Call the list tool again with no cursor to restart pagination."
}
}
}
}