read_purchases #

View this page as Markdown

On this page

Generated automatically from the published 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).

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 #

{
  "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 #

{
  "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
Additional properties: false
/properties/purchase A purchase id to read alone. An id absent from this account gives an empty list.

Type: string
Minimum length: 1

response #

JSON pointer Description and constraints
"" (root) Type: object
Required fields: ["contract_version","sales","amounts","currency","purchases","more","detail"]
/properties/contract_version Type: integer
Required value: 1
/properties/sales On only where credit sales are on and the purchase routes are configured. History is readable either way.

Type: string
Allowed values: ["off","on"]
/properties/amounts The allowed whole US dollar amounts for buy_credits.

Type: array
/properties/amounts/items Type: integer
Minimum: 1
/properties/currency The currency of the purchase amounts.

Type: string
Required value: usd
/properties/purchases This account's purchases, newest first by start instant and then by id. A purchase lookup returns at most one.

Type: array
Maximum items: 1000
/properties/purchases/items Type: object
Required fields: ["id","amount","amount_micros","currency","state","started_at","paid_at","ended_at"]
Additional properties: false
/properties/purchases/items/properties/id The purchase id.

Type: string
/properties/purchases/items/properties/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.

Type: string
/properties/purchases/items/properties/amount_micros The purchase amount before tax, in whole micro-dollars.

Type: integer
Minimum: 0
/properties/purchases/items/properties/currency The purchase's currency.

Type: string
/properties/purchases/items/properties/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.

Type: string
Allowed values: ["started","paid","expired","refunding","refunded","disputed","dispute_lost"]
/properties/purchases/items/properties/started_at The instant the purchase was opened.

Type: string
/properties/purchases/items/properties/paid_at The payment's instant, where known.

Type: ["string","null"]
/properties/purchases/items/properties/ended_at The instant the purchase ended, where known.

Type: ["string","null"]
/properties/purchases/items/properties/expires_at The paid purchase's grant expiry, where its grant is recorded. Absent otherwise, never null.

Type: string
/properties/more True where the latest-purchases bound cut the list. Always false for a purchase lookup.

Type: boolean
/properties/detail A fixed completion sentence. The read changes no purchase or credit.

Type: string
/properties/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.

Type: string
Pattern: ^[0-9a-f]{10}$

Complete payload contract #

{
  "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 #