---
title: "buy_credits"
description: "Generated reference for the management action buy_credits: its description, access metadata, payload contract, and registration status."
slug: /reference/actions/buy-credits
order: 5
visibility: public
redirects_from: []
---

# buy\_credits

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/buy_credits`, with a bearer credential and the action's payload as the JSON body. An MCP connection lists this action as the tool `buy_credits`.

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

Request a link for the account owner to buy account credit\. If credit sales are off on this site, the call refuses and opens no checkout\. The provider is the seller\. The owner opens the link and pays on the provider's page\. This tool pays nothing and the answer grants no credit\.

## More about this action

Pass an amount from the request's enumeration, in whole US dollars\. The call reads only your connection's account\. An unbilled account, an account blocked after a refund or dispute, or an account with an open dispute cannot buy\. A test\-mode site admits synthetic and operator accounts alone\.

Each call starts a new purchase and ends any earlier open checkout of the account\. Do not repeat a successful call to read its result: that starts another purchase\. The answer gives purchase, amount, currency, state and checkout\_url\. The state started means checkout was opened, not that payment was made\. Ask the account owner to open checkout\_url and pay on the provider's page\. The provider is the seller and adds any tax there\. This call pays nothing and grants no credit\.

The UTC day's limit counts the account's purchases paid that day, in any later state, plus the amount requested\. An earlier unpaid checkout is excluded because this start ends it\. The limit depends on the account's age\. A checkout ended by the plane that is paid all the same still grants credit, so that one payment can take the day over its limit\.

A verified paid event must identify the platform's purchase and match its amount before tax and US dollar currency\. Where the purchase already holds a provider session, the event must name it\. Both paid event kinds must report paid\. An unpaid completion grants nothing until paid; a failed or abandoned checkout grants nothing\. The grant expires from the payment event's own instant, not from checkout's start\. A repeat of the same paid event grants nothing again\.

## Access and action metadata

```json
{
  "name": "buy_credits",
  "resource": "account",
  "tier": "reversible",
  "surface": "account",
  "addresses": [
    "tzcloud",
    "tztools"
  ],
  "clients": [
    "bearer",
    "browser_session"
  ],
  "summary": "Request a link for the account owner to buy account credit. If credit sales are off on this site, the call refuses and opens no checkout. The provider is the seller. The owner opens the link and pays on the provider's page. This tool pays nothing and the answer grants no credit.",
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": false,
    "openWorldHint": true
  }
}
```

## MCP catalog entry

```json
{
  "name": "buy_credits",
  "title": "Request credit checkout",
  "tier": "reversible",
  "scenario": "CHI-L0-04",
  "summary": "Request a link for the account owner to buy account credit. If credit sales are off on this site, the call refuses and opens no checkout. The provider is the seller. The owner opens the link and pays on the provider's page. This tool pays nothing and the answer grants no credit.",
  "owners": [
    "ACB-L0-101",
    "ACB-L0-102"
  ]
}
```

## request

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["amount"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>amount | The credit to buy, in whole US dollars\. Use one of this member's enumerated amounts\.<br><br>Type: integer<br>Allowed values: \[25,50,100,250\] |

## response

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["contract\_version","purchase","amount","currency","state","checkout\_url","detail"\] |
| /<wbr>properties/<wbr>contract\_version | Required value: 1 |
| /<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\}$ |
| /<wbr>properties/<wbr>purchase | The purchase id generated by the platform\. It identifies no account\.<br><br>Type: string<br>Pattern: ^pur\_\[0\-9a\-f\]\{32\}$ |
| /<wbr>properties/<wbr>amount | The credit requested, in whole US dollars, before any tax\.<br><br>Type: integer |
| /<wbr>properties/<wbr>currency | The currency of the credit requested, US dollars\.<br><br>Required value: usd |
| /<wbr>properties/<wbr>state | Checkout was opened\. This state does not say payment was made or credit was granted\.<br><br>Required value: started |
| /<wbr>properties/<wbr>checkout\_url | The payment provider's checkout address\. The account owner opens it and pays there; the tool pays nothing\.<br><br>Type: string<br>Format: uri |
| /<wbr>properties/<wbr>detail | Who opens and pays at checkout, who sells the credit, and when credit is granted\. This answer grants no credit\.<br><br>Type: string |

## Complete payload contract

```json
{
  "request": {
    "type": "object",
    "required": [
      "amount"
    ],
    "properties": {
      "amount": {
        "type": "integer",
        "enum": [
          25,
          50,
          100,
          250
        ],
        "description": "The credit to buy, in whole US dollars. Use one of this member's enumerated amounts."
      }
    },
    "additionalProperties": false
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "purchase",
      "amount",
      "currency",
      "state",
      "checkout_url",
      "detail"
    ],
    "properties": {
      "contract_version": {
        "const": 1
      },
      "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."
      },
      "purchase": {
        "type": "string",
        "pattern": "^pur_[0-9a-f]{32}$",
        "description": "The purchase id generated by the platform. It identifies no account."
      },
      "amount": {
        "type": "integer",
        "description": "The credit requested, in whole US dollars, before any tax."
      },
      "currency": {
        "const": "usd",
        "description": "The currency of the credit requested, US dollars."
      },
      "state": {
        "const": "started",
        "description": "Checkout was opened. This state does not say payment was made or credit was granted."
      },
      "checkout_url": {
        "type": "string",
        "format": "uri",
        "description": "The payment provider's checkout address. The account owner opens it and pays there; the tool pays nothing."
      },
      "detail": {
        "type": "string",
        "description": "Who opens and pays at checkout, who sells the credit, and when credit is granted. This answer grants no credit."
      }
    }
  }
}
```

## 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/)
