read_purchases #
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 |
| / |
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"] |
| / |
Type: integer Required value: 1 |
| / |
On only where credit sales are on and the purchase routes are configured. History is readable either way. Type: string Allowed values: ["off","on"] |
| / |
The allowed whole US dollar amounts for buy_credits.Type: array |
| / |
Type: integer Minimum: 1 |
| / |
The currency of the purchase amounts. Type: string Required value: usd |
| / |
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 |
| / |
Type: object Required fields: ["id","amount","amount_micros","currency","state","started_at","paid_at","ended_at"] Additional properties: false |
| / |
The purchase id. Type: string |
| / |
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 |
| / |
The purchase amount before tax, in whole micro-dollars. Type: integer Minimum: 0 |
| / |
The purchase's currency. Type: string |
| / |
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"] |
| / |
The instant the purchase was opened. Type: string |
| / |
The payment's instant, where known. Type: ["string","null"] |
| / |
The instant the purchase ended, where known. Type: ["string","null"] |
| / |
The paid purchase's grant expiry, where its grant is recorded. Absent otherwise, never null. Type: string |
| / |
True where the latest-purchases bound cut the list. Always false for a purchase lookup. Type: boolean |
| / |
A fixed completion sentence. The read changes no purchase or credit. Type: string |
| / |
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 #
- Refusals: every refusal, by surface, with its cause and its remedy
- schemas/wire_error.schema.json
- schemas/wire_errors.json
- schemas/action_payloads.json (includes shared shapes)
- management_api_contract.md