> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# Check and change your Paddle account settings from your AI agent or the API

Set up your default payment link, payment methods, tax settings, and more using the Paddle API or your AI tools, without logging in to the dashboard.

---

## What's new?

You can now set up and check your Paddle account using the Paddle API, without logging in to the Paddle dashboard.

Get and update account settings like your [default payment link](https://developer.paddle.com/build/transactions/default-payment-link.md), checkout payment methods, tax settings, and balance currency. Check your [verification](https://developer.paddle.com/api-reference/verifications.md) status, create [client-side tokens](https://developer.paddle.com/api-reference/client-tokens.md), check that your [checkout domains](https://developer.paddle.com/api-reference/checkout-domains.md) are approved, and look up the [countries](https://developer.paddle.com/api-reference/countries.md) and [currencies](https://developer.paddle.com/api-reference/currencies.md) that Paddle supports.

AI agents connected to the [Paddle MCP server](https://developer.paddle.com/sdks/ai/paddle-mcp.md) can do all of this too, so you can ask an agent to set up checkout, check your account configuration, or tell you whether your account is ready to go live.

## How it works

### API root

{% api-endpoint method="GET" path="/" href="/api-reference/api-root/get-api-root" /%}

The [API root](https://developer.paddle.com/api-reference/api-root/get-api-root.md) returns details about the credentials that you're using, including which account you're authenticated against, whether you're working in sandbox or live, and the permissions that you have. Use it to check an API key or an MCP connection before you make other requests.

It doesn't require any permissions. A request with a key that isn't valid fails with a `403` error, and a request with no API key succeeds but doesn't include an account.

### Account

{% api-endpoint method="GET" path="/account" href="/api-reference/account/get-account" /%}
{% api-endpoint method="PATCH" path="/account" href="/api-reference/account/patch-account" /%}

[Account](https://developer.paddle.com/api-reference/account.md) operations return the business identity of the account that you're authenticated as, including its Paddle ID, legal name, display name, website, and contact email. Use them to check the business details that appear on invoices and other documents, or to update your contact email.

Getting your account requires the `account.read` permission, and updating it requires `account.write`. You can only update the contact email. To change anything else, contact Paddle support.

### Settings

[Settings](https://developer.paddle.com/api-reference/settings.md) operations let you get and update account-level settings for checkout, tax, and currencies. Use them to set up checkout and tax without the dashboard, or to check your configuration before you go live.

Each setting has its own read and write permissions, except checkout settings, which share `checkout_settings.read` and `checkout_settings.write`.

| Path | What it controls | Permissions |
|---|---|---|
| [`/settings/tax`](https://developer.paddle.com/api-reference/settings/get-tax-settings.md) | The default tax mode for prices with a `tax_mode` of `account_setting`. | `tax_settings.read`, `tax_settings.write` |
| [`/settings/balance-currency`](https://developer.paddle.com/api-reference/settings/get-balance-currency.md) | The currency that your balance is held in and paid out from. | `balance_currency.read`, `balance_currency.write` |
| [`/settings/currency-conversions`](https://developer.paddle.com/api-reference/settings/get-currency-conversions.md) | The currencies that Paddle automatically converts prices into for customers. | `currency_conversion.read`, `currency_conversion.write` |
| [`/settings/statement-descriptor`](https://developer.paddle.com/api-reference/settings/get-statement-descriptor-settings.md) | The name that appears on customer bank and card statements. | `statement_descriptor.read`, `statement_descriptor.write` |
| [`/settings/checkout-url`](https://developer.paddle.com/api-reference/settings/get-checkout-url.md) | Your [default payment link](https://developer.paddle.com/build/transactions/default-payment-link.md). | `checkout_settings.read`, `checkout_settings.write` |
| [`/settings/checkout-payment-methods`](https://developer.paddle.com/api-reference/settings/get-checkout-payment-method-settings.md) | The payment methods that are turned on at checkout. | `checkout_settings.read`, `checkout_settings.write` |
| [`/settings/checkout-features`](https://developer.paddle.com/api-reference/settings/get-checkout-features.md) | Discount codes, the marketing consent checkbox, and saved payment methods at checkout. | `checkout_settings.read`, `checkout_settings.write` |
| [`/settings/checkout-styles-overlay`](https://developer.paddle.com/api-reference/settings/get-checkout-styles-overlay.md) | The brand color used by overlay checkout. | `checkout_settings.read`, `checkout_settings.write` |
| [`/settings/checkout-recovery`](https://developer.paddle.com/api-reference/settings/get-checkout-recovery.md) | The email that Paddle sends when a customer abandons a checkout, and the discount that it offers. | `checkout_settings.read`, `checkout_settings.write` |

In live accounts, your default payment link must be on an approved domain. Submit domains for approval in the Paddle dashboard, then use [checkout domains](https://developer.paddle.com/api-reference/checkout-domains.md) to check that a domain is approved before you set it. In sandbox, the domain doesn't need to be approved.

### Verifications

{% api-endpoint method="GET" path="/verifications" href="/api-reference/verifications/list-verifications" /%}
{% api-endpoint method="GET" path="/verifications/{verification_id}" href="/api-reference/verifications/get-verification" /%}

[Verifications](https://developer.paddle.com/api-reference/verifications.md) show whether an account is ready for live payments, and which steps still need to be completed. Use them to check whether you can go live: list verifications with `verification_type=onboarding`, then check the `status`:

- `completed` means the account is ready.
- `action_required` means there's something to complete in the Paddle dashboard.

Verifications are read-only, only apply to live accounts, and require the `verification.read` permission.

### Countries and currencies

{% api-endpoint method="GET" path="/countries" href="/api-reference/countries/list-countries" /%}
{% api-endpoint method="GET" path="/currencies" href="/api-reference/currencies/list-currencies" /%}

[Countries](https://developer.paddle.com/api-reference/countries.md) and [currencies](https://developer.paddle.com/api-reference/currencies.md) return reference data about the countries that Paddle knows about and the currencies that Paddle supports. Use them to populate country and currency pickers, validate addresses, and check the minimum charge before you create a price.

They describe what Paddle supports, not what's turned on for your account, so they don't require any permissions.

## Configure your account from your AI tools

The [Paddle MCP server](https://developer.paddle.com/sdks/ai/paddle-mcp.md) and Paddle [agent skills](https://developer.paddle.com/sdks/ai/agent-skills.md) pick up the new operations, so you can ask an agent to check and configure your account without leaving your editor. For example:

- "Is my Paddle account ready to accept live payments, and what's outstanding?"
- "Set my default payment link to my checkout page."
- "Which payment methods are turned on for checkout, and what's my default tax mode?"

Updating settings requires write permissions, like `checkout_settings.write`. A live MCP server connected with OAuth starts with read access, so [grant write access](https://developer.paddle.com/sdks/ai/paddle-mcp.md#permissions) before you ask an agent to change settings.

If a request returns a `forbidden` error, your agent can get the API root to see which permissions it has, then tell you which one to add to your API key or MCP connection. You can also make the change in the Paddle dashboard.

{% callout type="warning" %}
Settings on a live account affect real checkouts, so review each change before you let an agent make it.
{% /callout %}

## Next steps

This change is available in version `1` of the Paddle API.

These are new operations, so it's a non-breaking change, meaning it doesn't impact existing integrations.

Existing API keys don't inherit the new permissions. To use the account, settings, and verification operations, add the permissions that you need to your API key. The API root, countries, and currencies operations don't need any permissions.

To get started, work through the [go-live checklist](https://developer.paddle.com/build/go-live-checklist.md). It shows how to complete each step in the Paddle dashboard or using the API. For the full reference, see the [API root](https://developer.paddle.com/api-reference/api-root.md), [account](https://developer.paddle.com/api-reference/account.md), [settings](https://developer.paddle.com/api-reference/settings.md), [verifications](https://developer.paddle.com/api-reference/verifications.md), [countries](https://developer.paddle.com/api-reference/countries.md), and [currencies](https://developer.paddle.com/api-reference/currencies.md) overviews.
## Summary of changes

| Name | Type | Change | Entity | Description |
| --- | --- | --- | --- | --- |
| GET / | API operation | added | API root | Check which account you're authenticated against, whether you're working in sandbox or live, and the permissions you have. |
| GET /account | API operation | added | Account | Get the business identity of the account that you're authenticated as. |
| PATCH /account | API operation | added | Account | Update the contact email for your account. |
| GET /settings/tax | API operation | added | Settings | Get tax settings for your account, including the default tax mode for prices. |
| PATCH /settings/tax | API operation | added | Settings | Update tax settings for your account. |
| GET /settings/balance-currency | API operation | added | Settings | Get the currency that your balance is held in and paid out from. |
| PATCH /settings/balance-currency | API operation | added | Settings | Update your preferred balance currency. |
| GET /settings/currency-conversions | API operation | added | Settings | Get the currencies that Paddle automatically converts prices into. |
| PATCH /settings/currency-conversions | API operation | added | Settings | Turn automatic price conversion on or off for currencies. |
| GET /settings/statement-descriptor | API operation | added | Settings | Get the name that appears on customer bank and card statements. |
| PATCH /settings/statement-descriptor | API operation | added | Settings | Update the name that appears on customer bank and card statements. |
| GET /settings/checkout-url | API operation | added | Settings | Get your default payment link. |
| PATCH /settings/checkout-url | API operation | added | Settings | Set or clear your default payment link. |
| GET /settings/checkout-payment-methods | API operation | added | Settings | Get the payment methods that are available on your account and enabled at checkout. |
| PATCH /settings/checkout-payment-methods | API operation | added | Settings | Turn payment methods on or off at checkout. |
| GET /settings/checkout-features | API operation | added | Settings | Get whether discount codes, the marketing consent checkbox, and saved payment methods are turned on at checkout. |
| PATCH /settings/checkout-features | API operation | added | Settings | Turn discount codes, the marketing consent checkbox, and saved payment methods on or off at checkout. |
| GET /settings/checkout-styles-overlay | API operation | added | Settings | Get the brand color used by overlay checkout. |
| PATCH /settings/checkout-styles-overlay | API operation | added | Settings | Update the brand color used by overlay checkout. |
| GET /settings/checkout-recovery | API operation | added | Settings | Get checkout recovery settings, including the discount offered in recovery emails. |
| PATCH /settings/checkout-recovery | API operation | added | Settings | Turn checkout recovery emails on or off, and set the discount that they offer. |
| GET /verifications | API operation | added | Verifications | List verifications for your account, so you can check whether it's ready for live payments. |
| GET /verifications/{verification_id} | API operation | added | Verifications | Get a verification using its ID. |
| GET /countries | API operation | added | Countries | List the countries that Paddle knows about, including whether Paddle supports sales there. |
| GET /currencies | API operation | added | Currencies | List the currencies that Paddle supports, including the decimal places used and the minimum charge. |
| `account.read` | Permission | added | API keys | New permission required to get your account. |
| `account.write` | Permission | added | API keys | New permission required to update your account. |
| `tax_settings.read` | Permission | added | API keys | New permission required to get tax settings. |
| `tax_settings.write` | Permission | added | API keys | New permission required to update tax settings. |
| `balance_currency.read` | Permission | added | API keys | New permission required to get your balance currency. |
| `balance_currency.write` | Permission | added | API keys | New permission required to update your balance currency. |
| `currency_conversion.read` | Permission | added | API keys | New permission required to get currency conversion settings. |
| `currency_conversion.write` | Permission | added | API keys | New permission required to update currency conversion settings. |
| `statement_descriptor.read` | Permission | added | API keys | New permission required to get your statement descriptor. |
| `statement_descriptor.write` | Permission | added | API keys | New permission required to update your statement descriptor. |
| `checkout_settings.read` | Permission | added | API keys | New permission required to get your default payment link, checkout payment methods, checkout features, overlay checkout styles, and checkout recovery settings. |
| `checkout_settings.write` | Permission | added | API keys | New permission required to update your default payment link, checkout payment methods, checkout features, overlay checkout styles, and checkout recovery settings. |
| `verification.read` | Permission | added | API keys | New permission required to list or get verifications. |