# List credit transactions (`list_credit_transactions`)

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.

- Source URL: https://www.signcustomiser.com/help/mcp/tools/list_credit_transactions/
- Markdown URL: https://www.signcustomiser.com/help/mcp/tools/list_credit_transactions.md
- MCP endpoint: https://mcp.signcustomiser.com
- Required scope: `billing:read`
- Behaviour: read

## Purpose

Explain where the Store AI credits went, or when credits were added, after get_store_billing reports the balance.

## Annotations

| Hint | Value |
| --- | --- |
| readOnlyHint | true |
| destructiveHint | false |
| idempotentHint | true |
| openWorldHint | false |

## Prerequisites

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

## Arguments

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | no | How many entries to return per page, between 1 and 100. Defaults to 20. |
| `cursor` | string | no | The opaque next_cursor value from the previous page. |

## Result

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

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `request_id` | string | yes |  |
| `store` | object | yes |  |
| `store.id` | integer | yes |  |
| `store.name` | string | yes |  |
| `transactions` | array of object | yes | The page of credit entries, newest first. |
| `transactions[].id` | integer | yes |  |
| `transactions[].type` | string | yes | One of: `credit`, `debit`. |
| `transactions[].bucket` | string | yes | One of: `plan`, `purchased`. |
| `transactions[].description` | string or null | no | The text the merchant admin shows. Do not parse it. |
| `transactions[].amount` | integer | yes | Credits changed; negative for a debit. |
| `transactions[].created_at` | string or null | no |  |
| `pagination` | object | yes |  |
| `pagination.has_more` | boolean | yes |  |
| `pagination.next_cursor` | string or null | no |  |

## Error cases

| Code | Recovery |
| --- | --- |
| `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. |

## Example: The two latest credit entries

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_credit_transactions",
    "arguments": {
      "limit": 2
    }
  }
}
```

Response:

```json
{
  "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"
      }
    }
  }
}
```

## Example: A cursor from another collection (error)

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_credit_transactions",
    "arguments": {
      "cursor": "eyJ2IjoxfQ"
    }
  }
}
```

Response:

```json
{
  "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."
      }
    }
  }
}
```
