> For the complete documentation index, see [llms.txt](https://docs.kinesis.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kinesis.network/mcp/tools/billing-management.md).

# Invoices and payment settings

Read invoices and ledger history, manage saved cards, redeem vouchers and configure node protection.

Read invoices and ledger history, manage saved cards, redeem vouchers and configure node protection.

These are action names. In default compact mode, call the indicated group tool with `{"action":"<action-name>","params":{...}}`; the arguments below go inside `params`. In `?mode=all`, call the action name directly with those arguments. `browse_github` and `read_docs` are direct tools in both modes. Expand each schema for nested fields, enum values and validation constraints. Successful results are JSON in both text content and `structuredContent`; failures use `isError` and `structuredContent.error`.

The [OpenAI profile](/mcp/openai-profile.md) calls individual actions, omits `get_byod_token`, and restricts credential inputs and environment outputs. The input schemas below describe the standard catalog; profile-specific schemas are included where they differ.

## `list_invoices`

List the organization's monthly invoices, newest first. Optionally for one month, status or date range

**Group:** `billing` · **Behavior:** Read

**Compact tool:** `billing` · **Action:** `list_invoices`

**MCP annotations:** `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Permissions and REST equivalents

| Operation               | REST                    | Required scopes |
| ----------------------- | ----------------------- | --------------- |
| `billing.invoices.list` | `GET /billing/invoices` | `billing:read`  |

### Arguments

| Argument | Type                             | Required | Description                                                                                      |
| -------- | -------------------------------- | -------- | ------------------------------------------------------------------------------------------------ |
| `year`   | `integer`                        | No       | Invoices of one year                                                                             |
| `month`  | `integer`                        | No       | Invoices of one month (with year)                                                                |
| `status` | `"draft" / "finalized" / "paid"` | No       | Invoices in this state                                                                           |
| `from`   | `string`                         | No       | Billing periods starting on or after this day, YYYY-MM-DD                                        |
| `to`     | `string`                         | No       | Billing periods ending on or before this day, YYYY-MM-DD                                         |
| `org`    | `string`                         | No       | Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one |

<details>

<summary>Complete input schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "year": {
      "type": "integer",
      "minimum": 2020,
      "maximum": 2100,
      "description": "Invoices of one year"
    },
    "month": {
      "type": "integer",
      "minimum": 1,
      "maximum": 12,
      "description": "Invoices of one month (with year)"
    },
    "status": {
      "type": "string",
      "enum": [
        "draft",
        "finalized",
        "paid"
      ],
      "description": "Invoices in this state"
    },
    "from": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Billing periods starting on or after this day, YYYY-MM-DD"
    },
    "to": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Billing periods ending on or before this day, YYYY-MM-DD"
    },
    "org": {
      "description": "Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one",
      "type": "string",
      "minLength": 3,
      "maxLength": 39
    }
  },
  "additionalProperties": false
}
```

</details>

### Result

* `invoices` (`array<object>`): See the complete response schema below.

<details>

<summary>Response schema: billing.invoices.list</summary>

```json
{
  "type": "object",
  "properties": {
    "invoices": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "number": {
            "type": "string",
            "description": "Invoice number; what the other invoice operations take"
          },
          "period": {
            "type": "object",
            "properties": {
              "start": {
                "type": "string",
                "description": "YYYY-MM-DD"
              },
              "end": {
                "type": "string",
                "description": "YYYY-MM-DD"
              }
            },
            "required": [
              "start",
              "end"
            ],
            "additionalProperties": false,
            "description": "Billing period, inclusive"
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "finalized",
              "paid"
            ]
          },
          "partialMonth": {
            "type": "boolean",
            "description": "The organization's billing began during the period"
          },
          "currency": {
            "type": "string"
          },
          "totalCents": {
            "type": "integer",
            "description": "Usage charged in the period"
          },
          "amountDueCents": {
            "type": "integer",
            "description": "What the organization owes on this invoice; 0 when credit covered it"
          },
          "closingBalanceCents": {
            "type": "integer",
            "description": "Balance at the end of the period; negative means owed"
          },
          "createdOn": {
            "type": "string",
            "description": "YYYY-MM-DD"
          },
          "updatedOn": {
            "anyOf": [
              {
                "type": "string",
                "description": "YYYY-MM-DD"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "number",
          "period",
          "status",
          "partialMonth",
          "currency",
          "totalCents",
          "amountDueCents",
          "closingBalanceCents",
          "createdOn",
          "updatedOn"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "invoices"
  ],
  "additionalProperties": false
}
```

</details>

Operation-specific errors: `400 org_required`, `403 key_project_restricted`.

## `get_invoice`

Get one invoice with its summary, itemized usage, payments and credits. The PDF is only available through the REST API (GET /v1/billing/invoices/{invoiceNumber}/pdf).

**Group:** `billing` · **Behavior:** Read

**Compact tool:** `billing` · **Action:** `get_invoice`

**MCP annotations:** `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Permissions and REST equivalents

| Operation              | REST                                    | Required scopes |
| ---------------------- | --------------------------------------- | --------------- |
| `billing.invoices.get` | `GET /billing/invoices/{invoiceNumber}` | `billing:read`  |

### Arguments

| Argument        | Type     | Required | Description                                                                                      |
| --------------- | -------- | -------- | ------------------------------------------------------------------------------------------------ |
| `invoiceNumber` | `string` | Yes      | Invoice number                                                                                   |
| `org`           | `string` | No       | Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one |

<details>

<summary>Complete input schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "invoiceNumber": {
      "type": "string",
      "minLength": 1,
      "description": "Invoice number"
    },
    "org": {
      "description": "Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one",
      "type": "string",
      "minLength": 3,
      "maxLength": 39
    }
  },
  "required": [
    "invoiceNumber"
  ],
  "additionalProperties": false
}
```

</details>

### Result

* `number` (`string`): Invoice number; what the other invoice operations take
* `period` (`object`): Billing period, inclusive
* `status` (`"draft" / "finalized" / "paid"`): See the complete response schema below.
* `partialMonth` (`boolean`): The organization's billing began during the period
* `currency` (`string`): See the complete response schema below.
* `totalCents` (`integer`): Usage charged in the period
* `amountDueCents` (`integer`): What the organization owes on this invoice; 0 when credit covered it
* `closingBalanceCents` (`integer`): Balance at the end of the period; negative means owed
* `createdOn` (`string`): YYYY-MM-DD
* `updatedOn` (`string or null`): See the complete response schema below.
* `customer` (`object`): See the complete response schema below.
* `statement` (`object`): The statement summary: how the balance moved over the period
* `items` (`array<object>`): Itemized usage
* `credits` (`array<object>`): Payments, promos, refunds and adjustments within the period
* `finalizedOn` (`string or null`): See the complete response schema below.
* `paidOn` (`string or null`): See the complete response schema below.

<details>

<summary>Response schema: billing.invoices.get</summary>

```json
{
  "type": "object",
  "properties": {
    "number": {
      "type": "string",
      "description": "Invoice number; what the other invoice operations take"
    },
    "period": {
      "type": "object",
      "properties": {
        "start": {
          "type": "string",
          "description": "YYYY-MM-DD"
        },
        "end": {
          "type": "string",
          "description": "YYYY-MM-DD"
        }
      },
      "required": [
        "start",
        "end"
      ],
      "additionalProperties": false,
      "description": "Billing period, inclusive"
    },
    "status": {
      "type": "string",
      "enum": [
        "draft",
        "finalized",
        "paid"
      ]
    },
    "partialMonth": {
      "type": "boolean",
      "description": "The organization's billing began during the period"
    },
    "currency": {
      "type": "string"
    },
    "totalCents": {
      "type": "integer",
      "description": "Usage charged in the period"
    },
    "amountDueCents": {
      "type": "integer",
      "description": "What the organization owes on this invoice; 0 when credit covered it"
    },
    "closingBalanceCents": {
      "type": "integer",
      "description": "Balance at the end of the period; negative means owed"
    },
    "createdOn": {
      "type": "string",
      "description": "YYYY-MM-DD"
    },
    "updatedOn": {
      "anyOf": [
        {
          "type": "string",
          "description": "YYYY-MM-DD"
        },
        {
          "type": "null"
        }
      ]
    },
    "customer": {
      "type": "object",
      "properties": {
        "email": {
          "type": "string"
        },
        "name": {
          "type": [
            "string",
            "null"
          ]
        },
        "billingEmail": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "email",
        "name",
        "billingEmail"
      ],
      "additionalProperties": false
    },
    "statement": {
      "type": "object",
      "properties": {
        "openingBalanceCents": {
          "type": "integer"
        },
        "closingBalanceCents": {
          "type": "integer"
        },
        "amountDueCents": {
          "type": "integer"
        },
        "paymentsCents": {
          "type": "integer",
          "description": "Card and off-platform payments received in the period"
        },
        "promosCents": {
          "type": "integer",
          "description": "Promotional credit granted in the period"
        },
        "refundsCents": {
          "type": "integer",
          "description": "Signed"
        },
        "adjustmentsCents": {
          "type": "integer",
          "description": "Signed"
        },
        "usageCents": {
          "type": "integer",
          "description": "Usage charged in the period"
        },
        "taxCents": {
          "type": "integer",
          "description": "Tax due on the amount owed; 0 when nothing is owed or no rate applies"
        },
        "taxRateBps": {
          "type": "integer",
          "description": "Tax rate the invoice was billed under, in basis points"
        }
      },
      "required": [
        "openingBalanceCents",
        "closingBalanceCents",
        "amountDueCents",
        "paymentsCents",
        "promosCents",
        "refundsCents",
        "adjustmentsCents",
        "usageCents",
        "taxCents",
        "taxRateBps"
      ],
      "additionalProperties": false,
      "description": "The statement summary: how the balance moved over the period"
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "resource": {
            "type": "string",
            "description": "What was billed, e.g. a GPU model, RAM, storage, a server"
          },
          "detail": {
            "type": [
              "string",
              "null"
            ]
          },
          "csp": {
            "type": [
              "string",
              "null"
            ]
          },
          "region": {
            "type": [
              "string",
              "null"
            ]
          },
          "zone": {
            "type": [
              "string",
              "null"
            ]
          },
          "kcRegion": {
            "type": [
              "string",
              "null"
            ]
          },
          "quantity": {
            "type": "number"
          },
          "unit": {
            "type": "string"
          },
          "unitPrice": {
            "type": "number",
            "description": "Price per unit, in currency units (fractional)"
          },
          "amount": {
            "type": "number",
            "description": "quantity times unitPrice, in currency units"
          }
        },
        "required": [
          "resource",
          "detail",
          "csp",
          "region",
          "zone",
          "kcRegion",
          "quantity",
          "unit",
          "unitPrice",
          "amount"
        ],
        "additionalProperties": false
      },
      "description": "Itemized usage"
    },
    "credits": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "ledgerEntryId": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "description": "Ledger entry type: credit_topup, manual_payment, a promo, refund, adjustment"
          },
          "at": {
            "type": "string",
            "description": "ISO 8601 timestamp"
          },
          "amountCents": {
            "type": "integer",
            "description": "Signed"
          },
          "label": {
            "type": "string"
          },
          "paymentMethod": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "brand": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "last4": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "brand",
                  "last4"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "ledgerEntryId",
          "type",
          "at",
          "amountCents",
          "label",
          "paymentMethod"
        ],
        "additionalProperties": false
      },
      "description": "Payments, promos, refunds and adjustments within the period"
    },
    "finalizedOn": {
      "anyOf": [
        {
          "type": "string",
          "description": "YYYY-MM-DD"
        },
        {
          "type": "null"
        }
      ]
    },
    "paidOn": {
      "anyOf": [
        {
          "type": "string",
          "description": "YYYY-MM-DD"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "number",
    "period",
    "status",
    "partialMonth",
    "currency",
    "totalCents",
    "amountDueCents",
    "closingBalanceCents",
    "createdOn",
    "updatedOn",
    "customer",
    "statement",
    "items",
    "credits",
    "finalizedOn",
    "paidOn"
  ],
  "additionalProperties": false
}
```

</details>

Operation-specific errors: `400 org_required`, `403 key_project_restricted`.

## `list_charges`

Usage charges summed per day or per hour, newest first. From the ledger, with the split between serverless apps, dedicated servers and spot leases

**Group:** `billing` · **Behavior:** Read

**Compact tool:** `billing` · **Action:** `list_charges`

**MCP annotations:** `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Permissions and REST equivalents

| Operation              | REST                   | Required scopes |
| ---------------------- | ---------------------- | --------------- |
| `billing.charges.list` | `GET /billing/charges` | `billing:read`  |

### Arguments

| Argument      | Type             | Required | Description                                                                                      |
| ------------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------ |
| `granularity` | `"day" / "hour"` | No       | Sum per day (default) or per hour                                                                |
| `from`        | `string`         | No       | First day to include, YYYY-MM-DD                                                                 |
| `to`          | `string`         | No       | Last day to include, YYYY-MM-DD                                                                  |
| `timeZone`    | `string`         | No       | IANA time zone the days are counted in, e.g. America/Los\_Angeles; UTC by default                |
| `limit`       | `integer`        | No       | Items per page, 1 to 200 (default 50)                                                            |
| `cursor`      | `string`         | No       | nextCursor from the previous page; omit for the first page                                       |
| `org`         | `string`         | No       | Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one |

<details>

<summary>Complete input schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "granularity": {
      "type": "string",
      "enum": [
        "day",
        "hour"
      ],
      "description": "Sum per day (default) or per hour"
    },
    "from": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "First day to include, YYYY-MM-DD"
    },
    "to": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Last day to include, YYYY-MM-DD"
    },
    "timeZone": {
      "type": "string",
      "description": "IANA time zone the days are counted in, e.g. America/Los_Angeles; UTC by default"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "description": "Items per page, 1 to 200 (default 50)"
    },
    "cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512,
      "description": "nextCursor from the previous page; omit for the first page"
    },
    "org": {
      "description": "Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one",
      "type": "string",
      "minLength": 3,
      "maxLength": 39
    }
  },
  "additionalProperties": false
}
```

</details>

### Result

* `charges` (`array<object>`): See the complete response schema below.
* `nextCursor` (`string or null`): Pass as cursor to fetch the next page; null on the last page

<details>

<summary>Response schema: billing.charges.list</summary>

```json
{
  "type": "object",
  "properties": {
    "charges": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "period": {
            "type": "string",
            "format": "date-time",
            "description": "Start of the day or hour, in the requested time zone"
          },
          "amountCents": {
            "type": "number",
            "description": "Usage charged in the period, including fractional cents"
          },
          "appsCents": {
            "type": "number",
            "description": "Of amountCents, serverless app usage"
          },
          "serversCents": {
            "type": "number",
            "description": "Of amountCents, dedicated servers"
          },
          "spotCents": {
            "type": "number",
            "description": "Of amountCents, spot leases"
          },
          "currency": {
            "type": "string"
          }
        },
        "required": [
          "period",
          "amountCents",
          "appsCents",
          "serversCents",
          "spotCents",
          "currency"
        ],
        "additionalProperties": false
      }
    },
    "nextCursor": {
      "description": "Pass as cursor to fetch the next page; null on the last page",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "charges",
    "nextCursor"
  ],
  "additionalProperties": false
}
```

</details>

Operation-specific errors: `400 org_required`, `403 key_project_restricted`.

## `list_credits`

Ledger entries that added or removed credit, newest first. Payments, promotional credit, refunds, adjustments

**Group:** `billing` · **Behavior:** Read

**Compact tool:** `billing` · **Action:** `list_credits`

**MCP annotations:** `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Permissions and REST equivalents

| Operation              | REST                   | Required scopes |
| ---------------------- | ---------------------- | --------------- |
| `billing.credits.list` | `GET /billing/credits` | `billing:read`  |

### Arguments

| Argument | Type                                                                                                                   | Required | Description                                                                                      |
| -------- | ---------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------ |
| `type`   | `"credit_topup" / "manual_payment" / "signup_promo" / "credit_promo" / "social_media_promo" / "refund" / "adjustment"` | No       | Only entries of this type                                                                        |
| `from`   | `string`                                                                                                               | No       | First day to include, YYYY-MM-DD (UTC)                                                           |
| `to`     | `string`                                                                                                               | No       | Last day to include, YYYY-MM-DD (UTC)                                                            |
| `limit`  | `integer`                                                                                                              | No       | Items per page, 1 to 200 (default 50)                                                            |
| `cursor` | `string`                                                                                                               | No       | nextCursor from the previous page; omit for the first page                                       |
| `org`    | `string`                                                                                                               | No       | Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one |

<details>

<summary>Complete input schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "credit_topup",
        "manual_payment",
        "signup_promo",
        "credit_promo",
        "social_media_promo",
        "refund",
        "adjustment"
      ],
      "description": "Only entries of this type"
    },
    "from": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "First day to include, YYYY-MM-DD (UTC)"
    },
    "to": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Last day to include, YYYY-MM-DD (UTC)"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "description": "Items per page, 1 to 200 (default 50)"
    },
    "cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512,
      "description": "nextCursor from the previous page; omit for the first page"
    },
    "org": {
      "description": "Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one",
      "type": "string",
      "minLength": 3,
      "maxLength": 39
    }
  },
  "additionalProperties": false
}
```

</details>

### Result

* `entries` (`array<object>`): See the complete response schema below.
* `nextCursor` (`string or null`): Pass as cursor to fetch the next page; null on the last page

<details>

<summary>Response schema: billing.credits.list</summary>

```json
{
  "type": "object",
  "properties": {
    "entries": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Ledger entry id"
          },
          "at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp (UTC)"
          },
          "type": {
            "type": "string",
            "enum": [
              "credit_topup",
              "manual_payment",
              "signup_promo",
              "credit_promo",
              "social_media_promo",
              "refund",
              "adjustment"
            ],
            "description": "credit_topup and manual_payment are money in; the promos are granted credit"
          },
          "amountCents": {
            "type": "integer",
            "description": "Signed: positive adds credit, negative removes it"
          },
          "currency": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "description": "succeeded, pending or failed"
          },
          "paymentMethod": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "brand": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "last4": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "brand",
                  "last4"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ],
            "description": "The card charged, for card payments"
          },
          "note": {
            "description": "A note left by the person who recorded a manual entry",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "at",
          "type",
          "amountCents",
          "currency",
          "status",
          "paymentMethod",
          "note"
        ],
        "additionalProperties": false
      }
    },
    "nextCursor": {
      "description": "Pass as cursor to fetch the next page; null on the last page",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "entries",
    "nextCursor"
  ],
  "additionalProperties": false
}
```

</details>

Operation-specific errors: `400 org_required`, `403 key_project_restricted`.

## `list_payment_methods`

List the organization's saved cards and which one is the default

**Group:** `billing` · **Behavior:** Read

**Compact tool:** `billing` · **Action:** `list_payment_methods`

**MCP annotations:** `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Permissions and REST equivalents

| Operation                     | REST                           | Required scopes |
| ----------------------------- | ------------------------------ | --------------- |
| `billing.paymentMethods.list` | `GET /billing/payment-methods` | `billing:read`  |

### Arguments

| Argument | Type     | Required | Description                                                                                      |
| -------- | -------- | -------- | ------------------------------------------------------------------------------------------------ |
| `org`    | `string` | No       | Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one |

<details>

<summary>Complete input schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "org": {
      "description": "Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one",
      "type": "string",
      "minLength": 3,
      "maxLength": 39
    }
  },
  "additionalProperties": false
}
```

</details>

### Result

* `paymentMethods` (`array<object>`): See the complete response schema below.

<details>

<summary>Response schema: billing.paymentMethods.list</summary>

```json
{
  "type": "object",
  "properties": {
    "paymentMethods": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Payment method id"
          },
          "brand": {
            "description": "Card brand, e.g. visa",
            "type": [
              "string",
              "null"
            ]
          },
          "last4": {
            "type": [
              "string",
              "null"
            ]
          },
          "expMonth": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "expYear": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "default": {
            "type": "boolean",
            "description": "The card auto-reload and top-ups charge"
          },
          "addedAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp (UTC)"
          }
        },
        "required": [
          "id",
          "brand",
          "last4",
          "expMonth",
          "expYear",
          "default",
          "addedAt"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "paymentMethods"
  ],
  "additionalProperties": false
}
```

</details>

Operation-specific errors: `400 org_required`, `403 key_project_restricted`.

## `set_default_payment_method`

Make a saved card the default for auto-reload and top-ups

**Group:** `billing` · **Behavior:** Write

**Compact tool:** `billing_write` · **Action:** `set_default_payment_method`

**MCP annotations:** `readOnlyHint: false` · `destructiveHint: true` · `idempotentHint: true` · `openWorldHint: false`

### Permissions and REST equivalents

| Operation                           | REST                                                      | Required scopes |
| ----------------------------------- | --------------------------------------------------------- | --------------- |
| `billing.paymentMethods.setDefault` | `POST /billing/payment-methods/{paymentMethodId}/default` | `billing:write` |

### Arguments

| Argument          | Type     | Required | Description                                                                                      |
| ----------------- | -------- | -------- | ------------------------------------------------------------------------------------------------ |
| `paymentMethodId` | `string` | Yes      | Payment method id from the list                                                                  |
| `org`             | `string` | No       | Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one |

<details>

<summary>Complete input schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "paymentMethodId": {
      "type": "string",
      "minLength": 1,
      "description": "Payment method id from the list"
    },
    "org": {
      "description": "Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one",
      "type": "string",
      "minLength": 3,
      "maxLength": 39
    }
  },
  "required": [
    "paymentMethodId"
  ],
  "additionalProperties": false
}
```

</details>

### Result

* `paymentMethods` (`array<object>`): See the complete response schema below.

<details>

<summary>Response schema: billing.paymentMethods.setDefault</summary>

```json
{
  "type": "object",
  "properties": {
    "paymentMethods": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Payment method id"
          },
          "brand": {
            "description": "Card brand, e.g. visa",
            "type": [
              "string",
              "null"
            ]
          },
          "last4": {
            "type": [
              "string",
              "null"
            ]
          },
          "expMonth": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "expYear": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "default": {
            "type": "boolean",
            "description": "The card auto-reload and top-ups charge"
          },
          "addedAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp (UTC)"
          }
        },
        "required": [
          "id",
          "brand",
          "last4",
          "expMonth",
          "expYear",
          "default",
          "addedAt"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "paymentMethods"
  ],
  "additionalProperties": false
}
```

</details>

Operation-specific errors: `404 not_found`, `400 org_required`, `403 key_project_restricted`.

## `remove_payment_method`

Remove a saved card. A removed default is replaced by the next saved card; auto-reload is switched off when no card is left.

**Group:** `billing` · **Behavior:** Write

**Compact tool:** `billing_write` · **Action:** `remove_payment_method`

**MCP annotations:** `readOnlyHint: false` · `destructiveHint: true` · `idempotentHint: false` · `openWorldHint: false`

Requires `confirm: true` for this irreversible action.

### Permissions and REST equivalents

| Operation                       | REST                                                | Required scopes |
| ------------------------------- | --------------------------------------------------- | --------------- |
| `billing.paymentMethods.remove` | `DELETE /billing/payment-methods/{paymentMethodId}` | `billing:write` |

### Arguments

| Argument          | Type     | Required | Description                                                                                      |
| ----------------- | -------- | -------- | ------------------------------------------------------------------------------------------------ |
| `paymentMethodId` | `string` | Yes      | Payment method id from the list                                                                  |
| `confirm`         | `true`   | Yes      | Must be true: this action cannot be undone                                                       |
| `org`             | `string` | No       | Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one |

<details>

<summary>Complete input schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "paymentMethodId": {
      "type": "string",
      "minLength": 1,
      "description": "Payment method id from the list"
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Must be true: this action cannot be undone"
    },
    "org": {
      "description": "Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one",
      "type": "string",
      "minLength": 3,
      "maxLength": 39
    }
  },
  "required": [
    "paymentMethodId",
    "confirm"
  ],
  "additionalProperties": false
}
```

</details>

### Result

* `paymentMethods` (`array<object>`): The cards that remain
* `autoReloadDisabled` (`boolean`): Auto-reload was switched off because no card is left

<details>

<summary>Response schema: billing.paymentMethods.remove</summary>

```json
{
  "type": "object",
  "properties": {
    "paymentMethods": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Payment method id"
          },
          "brand": {
            "description": "Card brand, e.g. visa",
            "type": [
              "string",
              "null"
            ]
          },
          "last4": {
            "type": [
              "string",
              "null"
            ]
          },
          "expMonth": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "expYear": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "default": {
            "type": "boolean",
            "description": "The card auto-reload and top-ups charge"
          },
          "addedAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp (UTC)"
          }
        },
        "required": [
          "id",
          "brand",
          "last4",
          "expMonth",
          "expYear",
          "default",
          "addedAt"
        ],
        "additionalProperties": false
      },
      "description": "The cards that remain"
    },
    "autoReloadDisabled": {
      "type": "boolean",
      "description": "Auto-reload was switched off because no card is left"
    }
  },
  "required": [
    "paymentMethods",
    "autoReloadDisabled"
  ],
  "additionalProperties": false
}
```

</details>

Operation-specific errors: `404 not_found`, `400 org_required`, `403 key_project_restricted`.

## `redeem_voucher`

Redeem a voucher code for organization credit; once per person per code

**Group:** `billing` · **Behavior:** Write

**Compact tool:** `billing_write` · **Action:** `redeem_voucher`

**MCP annotations:** `readOnlyHint: false` · `destructiveHint: true` · `idempotentHint: false` · `openWorldHint: false`

### Permissions and REST equivalents

| Operation                 | REST                            | Required scopes |
| ------------------------- | ------------------------------- | --------------- |
| `billing.vouchers.redeem` | `POST /billing/vouchers/redeem` | `billing:write` |

### Arguments

| Argument | Type     | Required | Description                                                                                      |
| -------- | -------- | -------- | ------------------------------------------------------------------------------------------------ |
| `code`   | `string` | Yes      | The voucher code                                                                                 |
| `org`    | `string` | No       | Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one |

<details>

<summary>Complete input schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "The voucher code"
    },
    "org": {
      "description": "Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one",
      "type": "string",
      "minLength": 3,
      "maxLength": 39
    }
  },
  "required": [
    "code"
  ],
  "additionalProperties": false
}
```

</details>

### Result

* `amountCents` (`integer`): Credit added to the balance
* `redemptionsRemaining` (`integer or null`): Uses the voucher has left

<details>

<summary>Response schema: billing.vouchers.redeem</summary>

```json
{
  "type": "object",
  "properties": {
    "amountCents": {
      "type": "integer",
      "description": "Credit added to the balance"
    },
    "redemptionsRemaining": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Uses the voucher has left"
    }
  },
  "required": [
    "amountCents",
    "redemptionsRemaining"
  ],
  "additionalProperties": false
}
```

</details>

Operation-specific errors: `404 voucher_not_found`, `400 voucher_rejected`, `429 too_many_attempts`, `400 org_required`, `403 key_project_restricted`.

## `get_node_protection`

Read the organization's node protection setting. Whether its dedicated servers are hibernated automatically when the balance is about to run out, and at how many hours of runway

**Group:** `billing` · **Behavior:** Read

**Compact tool:** `billing` · **Action:** `get_node_protection`

**MCP annotations:** `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Permissions and REST equivalents

| Operation                    | REST                           | Required scopes |
| ---------------------------- | ------------------------------ | --------------- |
| `billing.nodeProtection.get` | `GET /billing/node-protection` | `billing:read`  |

### Arguments

| Argument | Type     | Required | Description                                                                                      |
| -------- | -------- | -------- | ------------------------------------------------------------------------------------------------ |
| `org`    | `string` | No       | Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one |

<details>

<summary>Complete input schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "org": {
      "description": "Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one",
      "type": "string",
      "minLength": 3,
      "maxLength": 39
    }
  },
  "additionalProperties": false
}
```

</details>

### Result

* `enabled` (`boolean`): The organization's dedicated servers are hibernated when the balance runs low
* `thresholdHours` (`integer or null`): Hours of runway left (balance over spend rate) at which the servers are hibernated; null when off
* `hibernatedAt` (`string or null`): When protection last hibernated the servers
* `deprovisionedAt` (`string or null`): When a balance past its limit last deprovisioned them

<details>

<summary>Response schema: billing.nodeProtection.get</summary>

```json
{
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean",
      "description": "The organization's dedicated servers are hibernated when the balance runs low"
    },
    "thresholdHours": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Hours of runway left (balance over spend rate) at which the servers are hibernated; null when off"
    },
    "hibernatedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp (UTC)"
        },
        {
          "type": "null"
        }
      ],
      "description": "When protection last hibernated the servers"
    },
    "deprovisionedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp (UTC)"
        },
        {
          "type": "null"
        }
      ],
      "description": "When a balance past its limit last deprovisioned them"
    }
  },
  "required": [
    "enabled",
    "thresholdHours",
    "hibernatedAt",
    "deprovisionedAt"
  ],
  "additionalProperties": false
}
```

</details>

Operation-specific errors: `400 org_required`, `403 key_project_restricted`.

## `set_node_protection`

Turn node protection on with a runway threshold, or off. On: when the balance would run out within thresholdHours at the current spend rate, the organization's dedicated servers are hibernated (storage only) until credits are added.

**Group:** `billing` · **Behavior:** Write

**Compact tool:** `billing_write` · **Action:** `set_node_protection`

**MCP annotations:** `readOnlyHint: false` · `destructiveHint: true` · `idempotentHint: true` · `openWorldHint: false`

### Permissions and REST equivalents

| Operation                       | REST                             | Required scopes |
| ------------------------------- | -------------------------------- | --------------- |
| `billing.nodeProtection.update` | `PATCH /billing/node-protection` | `billing:write` |

### Arguments

| Argument         | Type      | Required | Description                                                                                      |
| ---------------- | --------- | -------- | ------------------------------------------------------------------------------------------------ |
| `enabled`        | `boolean` | Yes      | Turn protection on or off                                                                        |
| `thresholdHours` | `integer` | No       | Hours of runway that trigger hibernation, 2 to 48; required when enabling                        |
| `org`            | `string`  | No       | Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one |

<details>

<summary>Complete input schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean",
      "description": "Turn protection on or off"
    },
    "thresholdHours": {
      "type": "integer",
      "minimum": 2,
      "maximum": 48,
      "description": "Hours of runway that trigger hibernation, 2 to 48; required when enabling"
    },
    "org": {
      "description": "Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one",
      "type": "string",
      "minLength": 3,
      "maxLength": 39
    }
  },
  "required": [
    "enabled"
  ],
  "additionalProperties": false
}
```

</details>

### Result

* `enabled` (`boolean`): The organization's dedicated servers are hibernated when the balance runs low
* `thresholdHours` (`integer or null`): Hours of runway left (balance over spend rate) at which the servers are hibernated; null when off
* `hibernatedAt` (`string or null`): When protection last hibernated the servers
* `deprovisionedAt` (`string or null`): When a balance past its limit last deprovisioned them

<details>

<summary>Response schema: billing.nodeProtection.update</summary>

```json
{
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean",
      "description": "The organization's dedicated servers are hibernated when the balance runs low"
    },
    "thresholdHours": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Hours of runway left (balance over spend rate) at which the servers are hibernated; null when off"
    },
    "hibernatedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp (UTC)"
        },
        {
          "type": "null"
        }
      ],
      "description": "When protection last hibernated the servers"
    },
    "deprovisionedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp (UTC)"
        },
        {
          "type": "null"
        }
      ],
      "description": "When a balance past its limit last deprovisioned them"
    }
  },
  "required": [
    "enabled",
    "thresholdHours",
    "hibernatedAt",
    "deprovisionedAt"
  ],
  "additionalProperties": false
}
```

</details>

Operation-specific errors: `400 org_required`, `403 key_project_restricted`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.kinesis.network/mcp/tools/billing-management.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.