---
title: "read_purchases"
description: "Generated reference for the management action read_purchases: its description, access metadata, payload contract, and registration status."
slug: /reference/actions/read-purchases
order: 4
visibility: public
redirects_from: []
---

# read\_purchases

Generated automatically from the [published contract sources](/cloud/reference/about/#contract-sources).

A script calls this action over HTTPS at `POST https://turnzero.ai/api/v1/read_purchases`, with a bearer credential and the action's payload as the JSON body. It also accepts `GET`. An MCP connection lists this action as the tool `read_purchases`.

OAuth access tokens and minted tokens, including the turnzero command's computer token, are bearer credentials. The action determines which kinds, scopes and grants it accepts ([Sign-in, sessions, and tokens](/cloud/concepts/sign-in-sessions-and-tokens/)).

**Build metadata:** Registered in this build. Registration describes the default dispatcher in this build. It does not guarantee that a caller has the required credential or grant, that a tool is listed for that connection, or that the required service is configured.

## Contract description

Read your account's credit purchases, newest first, including each purchase's state and its grant's expiry where recorded\. Pass `purchase` for one id\. An id belonging to another account gives an empty list\. The answer includes whether sales are open, the purchase amounts and currency\. This read changes nothing\.

## More about this action

The read takes no account argument and reads only the account your connection represents\. Without `purchase`, it returns at most 1000 purchases, ordered by start instant newest first, then by id\. `more` is true where the list was cut\. Pass a purchase id to read it alone\. An id that does not exist or belongs to another account gives an empty list with `more: false`\. A supplied value that is not non\-empty text is refused `invalid_request`\.

Amounts are before tax, as dollars strings and exact micro\-dollar integers\. Each purchase gives its state, start, payment and end instants, the latter two null where no instant is recorded\. `expires_at` is the grant's expiry for a paid purchase whose grant is recorded, absent otherwise and never null\. No provider identifier or refund amount is answered\.

`sales` is `on` only where the estate's `credit_sales` is on and purchase routes are configured\. It is off otherwise\. History reads either way\. `amounts` gives the allowed whole\-dollar purchase values and `currency` their currency\. The read opens no checkout, asks the provider nothing and writes nothing\.

## Access and action metadata

```json
{
  "name": "read_purchases",
  "resource": "account",
  "tier": "observe",
  "surface": "account",
  "addresses": [
    "tzcloud",
    "tztools"
  ],
  "clients": [
    "bearer",
    "browser_session"
  ],
  "summary": "Read your account's credit purchases, newest first, including each purchase's state and its grant's expiry where recorded. Pass `purchase` for one id. An id belonging to another account gives an empty list. The answer includes whether sales are open, the purchase amounts and currency. This read changes nothing.",
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": false,
    "idempotentHint": true
  }
}
```

## MCP catalog entry

```json
{
  "name": "read_purchases",
  "title": "Read credit purchases",
  "tier": "observe",
  "scenario": "CHI-L0-04",
  "summary": "Read your account's credit purchases, newest first, including each purchase's state and its grant's expiry where recorded. Pass `purchase` for one id. An id belonging to another account gives an empty list. The answer includes whether sales are open, the purchase amounts and currency. This read changes nothing.",
  "owners": [
    "API-L0-27",
    "ACB-L0-44",
    "ACB-L0-101",
    "ACB-L0-102"
  ]
}
```

## request

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Additional properties: false |
| /<wbr>properties/<wbr>purchase | A purchase id to read alone\. An id absent from this account gives an empty list\.<br><br>Type: string<br>Minimum length: 1 |

## response

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["contract\_version","sales","amounts","currency","purchases","more","detail"\] |
| /<wbr>properties/<wbr>contract\_version | Type: integer<br>Required value: 1 |
| /<wbr>properties/<wbr>sales | On only where credit sales are on and the purchase routes are configured\. History is readable either way\.<br><br>Type: string<br>Allowed values: \["off","on"\] |
| /<wbr>properties/<wbr>amounts | The allowed whole US dollar amounts for `buy_credits`\.<br><br>Type: array |
| /<wbr>properties/<wbr>amounts/<wbr>items | Type: integer<br>Minimum: 1 |
| /<wbr>properties/<wbr>currency | The currency of the purchase amounts\.<br><br>Type: string<br>Required value: usd |
| /<wbr>properties/<wbr>purchases | This account's purchases, newest first by start instant and then by id\. A purchase lookup returns at most one\.<br><br>Type: array<br>Maximum items: 1000 |
| /<wbr>properties/<wbr>purchases/<wbr>items | Type: object<br>Required fields: \["id","amount","amount\_micros","currency","state","started\_at","paid\_at","ended\_at"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>purchases/<wbr>items/<wbr>properties/<wbr>id | The purchase id\.<br><br>Type: string |
| /<wbr>properties/<wbr>purchases/<wbr>items/<wbr>properties/<wbr>amount | The purchase amount before tax, as a dollars string\. A dollars string starts with a dollar sign, separates thousands with commas and is rounded to two decimal places\. A positive amount below one cent is rounded to four\.<br><br>Type: string |
| /<wbr>properties/<wbr>purchases/<wbr>items/<wbr>properties/<wbr>amount\_micros | The purchase amount before tax, in whole micro\-dollars\.<br><br>Type: integer<br>Minimum: 0 |
| /<wbr>properties/<wbr>purchases/<wbr>items/<wbr>properties/<wbr>currency | The purchase's currency\.<br><br>Type: string |
| /<wbr>properties/<wbr>purchases/<wbr>items/<wbr>properties/<wbr>state | `started`: a checkout request was recorded and grants no credit\. `paid`: payment was recorded and credit granted\. `expired`: checkout abandoned or payment failed\. `refunding` and `refunded`: a refund on its way and done\. `disputed`: a dispute removed remaining credit\. `dispute_lost`: it closed against the seller\. A dispute resolved for the seller returns the state to `paid`\.<br><br>Type: string<br>Allowed values: \["started","paid","expired","refunding","refunded","disputed","dispute\_lost"\] |
| /<wbr>properties/<wbr>purchases/<wbr>items/<wbr>properties/<wbr>started\_at | The instant the purchase was opened\.<br><br>Type: string |
| /<wbr>properties/<wbr>purchases/<wbr>items/<wbr>properties/<wbr>paid\_at | The payment's instant, where known\.<br><br>Type: \["string","null"\] |
| /<wbr>properties/<wbr>purchases/<wbr>items/<wbr>properties/<wbr>ended\_at | The instant the purchase ended, where known\.<br><br>Type: \["string","null"\] |
| /<wbr>properties/<wbr>purchases/<wbr>items/<wbr>properties/<wbr>expires\_at | The paid purchase's grant expiry, where its grant is recorded\. Absent otherwise, never null\.<br><br>Type: string |
| /<wbr>properties/<wbr>more | True where the latest\-purchases bound cut the list\. Always false for a purchase lookup\.<br><br>Type: boolean |
| /<wbr>properties/<wbr>detail | A fixed completion sentence\. The read changes no purchase or credit\.<br><br>Type: string |
| /<wbr>properties/<wbr>reference | The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row\. Quote it when you report the call\.<br><br>Type: string<br>Pattern: ^\[0\-9a\-f\]\{10\}$ |

## Complete payload contract

```json
{
  "request": {
    "type": "object",
    "properties": {
      "purchase": {
        "type": "string",
        "minLength": 1,
        "description": "A purchase id to read alone. An id absent from this account gives an empty list."
      }
    },
    "additionalProperties": false
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "sales",
      "amounts",
      "currency",
      "purchases",
      "more",
      "detail"
    ],
    "properties": {
      "contract_version": {
        "type": "integer",
        "const": 1
      },
      "sales": {
        "type": "string",
        "enum": [
          "off",
          "on"
        ],
        "description": "On only where credit sales are on and the purchase routes are configured. History is readable either way."
      },
      "amounts": {
        "type": "array",
        "items": {
          "type": "integer",
          "minimum": 1
        },
        "description": "The allowed whole US dollar amounts for `buy_credits`."
      },
      "currency": {
        "type": "string",
        "const": "usd",
        "description": "The currency of the purchase amounts."
      },
      "purchases": {
        "type": "array",
        "maxItems": 1000,
        "description": "This account's purchases, newest first by start instant and then by id. A purchase lookup returns at most one.",
        "items": {
          "type": "object",
          "required": [
            "id",
            "amount",
            "amount_micros",
            "currency",
            "state",
            "started_at",
            "paid_at",
            "ended_at"
          ],
          "properties": {
            "id": {
              "type": "string",
              "description": "The purchase id."
            },
            "amount": {
              "type": "string",
              "description": "The purchase amount before tax, as a dollars string. A dollars string starts with a dollar sign, separates thousands with commas and is rounded to two decimal places. A positive amount below one cent is rounded to four."
            },
            "amount_micros": {
              "type": "integer",
              "minimum": 0,
              "description": "The purchase amount before tax, in whole micro-dollars."
            },
            "currency": {
              "type": "string",
              "description": "The purchase's currency."
            },
            "state": {
              "type": "string",
              "enum": [
                "started",
                "paid",
                "expired",
                "refunding",
                "refunded",
                "disputed",
                "dispute_lost"
              ],
              "description": "`started`: a checkout request was recorded and grants no credit. `paid`: payment was recorded and credit granted. `expired`: checkout abandoned or payment failed. `refunding` and `refunded`: a refund on its way and done. `disputed`: a dispute removed remaining credit. `dispute_lost`: it closed against the seller. A dispute resolved for the seller returns the state to `paid`."
            },
            "started_at": {
              "type": "string",
              "description": "The instant the purchase was opened."
            },
            "paid_at": {
              "type": [
                "string",
                "null"
              ],
              "description": "The payment's instant, where known."
            },
            "ended_at": {
              "type": [
                "string",
                "null"
              ],
              "description": "The instant the purchase ended, where known."
            },
            "expires_at": {
              "type": "string",
              "description": "The paid purchase's grant expiry, where its grant is recorded. Absent otherwise, never null."
            }
          },
          "additionalProperties": false
        }
      },
      "more": {
        "type": "boolean",
        "description": "True where the latest-purchases bound cut the list. Always false for a purchase lookup."
      },
      "detail": {
        "type": "string",
        "description": "A fixed completion sentence. The read changes no purchase or credit."
      },
      "reference": {
        "type": "string",
        "pattern": "^[0-9a-f]{10}$",
        "description": "The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row. Quote it when you report the call."
      }
    }
  }
}
```

## Shared contracts

- [Refusals](/cloud/reference/refusals/): every refusal, by surface, with its cause and its remedy
- [schemas/wire\_error\.schema\.json](/cloud/reference/sources/schemas/wire-error-schema/)
- [schemas/wire\_errors\.json](/cloud/reference/sources/schemas/wire-errors/)
- [schemas/action\_payloads\.json](/cloud/reference/sources/schemas/action-payloads/) (includes shared shapes)
- [management\_api\_contract\.md](/cloud/reference/sources/management-api-contract/)
