Sign Customiser

Navigation

Dark mode

Billing

list_credit_transactions

read

List credit transactions

Copy page

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

readOnlyHinttrue
destructiveHintfalse
idempotentHinttrue
openWorldHintfalse

Prerequisites

  • A merchant has connected this store and approved the billing:read scope.

Arguments

limitinteger

How many entries to return per page, between 1 and 100. Defaults to 20.

cursorstring

The opaque next_cursor value from the previous page.

Result

Up to `limit` credit entries, newest first, plus the cursor for the next page.

request_idstringalways present
storeobjectalways present
store.idintegeralways present
store.namestringalways present
transactionsarray of objectalways present

The page of credit entries, newest first.

transactions[].idintegeralways present
transactions[].typestringalways present

One of: credit, debit

transactions[].bucketstringalways present

One of: plan, purchased

transactions[].descriptionstring or null

The text the merchant admin shows. Do not parse it.

transactions[].amountintegeralways present

Credits changed; negative for a debit.

transactions[].created_atstring or null
paginationobjectalways present
pagination.has_morebooleanalways present
pagination.next_cursorstring or null

Error cases

insufficient_scope

The connection was approved without billing:read.

invalid_cursor

The cursor was altered or reused for a different collection or Store; restart with no cursor.

invalid_parameter

limit is not an integer from 1 to 100.

The two latest credit entries

tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_credit_transactions",
    "arguments": {
      "limit": 2
    }
  }
}
result
{
  "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)

tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_credit_transactions",
    "arguments": {
      "cursor": "eyJ2IjoxfQ"
    }
  }
}
result
{
  "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."
      }
    }
  }
}

Type a question and press Enter. Use the arrow keys to move between the results.