---
name: configure-seller-account
description: Configure a seller's account settings with the seller `api_key` — the default payment link (`PATCH /settings/account`), tax mode, brand color, saved payment methods, the bank statement descriptor, and enabling payment methods.
metadata:
  internal: true
---

# Configure seller account settings

## When to use this skill

Use this skill right after [creating a seller account](/partners/embed-billing/onboard-sellers/create-seller), and whenever a seller changes something that maps to account settings — checkout defaults, statement descriptor, tax handling, brand color, or payment methods. Configure these automatically from what you already know about the user; you don't usually need a form. Also make them available to your platform agent so it can update settings as the user makes changes.

These calls use the **seller's `api_key`** as the Bearer token (see [`partner-api-basics`](/partners/embed-billing/get-started/api-basics)). Make each request against **both** sandbox and live — with one exception noted below.

## 1. Account settings — `PATCH /settings/account`

Configures the default payment link, tax mode, brand color, and whether customers can save payment methods.

Recommended defaults:

- `default_tax_mode`: `"location"` — shows prices tax-inclusive or tax-exclusive based on the customer's region.
- `primary_checkout_color`: infer from the seller's brand palette.
- `saved_payment_methods_enabled`: `true` — improves conversion for repeat customers.

```bash
curl -X PATCH https://sandbox-api.paddle.com/settings/account \
  -H "Authorization: Bearer $SELLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "default_checkout_url": "https://aeroedit.com/checkout",
    "default_tax_mode": "location",
    "primary_checkout_color": "#f0f0f0",
    "saved_payment_methods_enabled": true
  }'
```

**The default payment link is required to open a checkout.** Without it, Paddle Checkout fails with "Something went wrong."

- On **sandbox**, set any URL — `localhost` or the seller's homepage is fine. No approval needed.
- On **live**, the domain must be a verified, approved [checkout domain](/partners/embed-billing/seller-go-live/checkout-domains) first. **Omit `default_checkout_url` on live during onboarding** and set it later, as part of go-live, once the domain is approved. A user still building in sandbox usually hasn't deployed, so live domain review would fail.

## 2. Statement descriptor — `PATCH /settings/statement-descriptor`

The name customers see on their bank statement. Only `name` is settable; the other fields are returned for reference.

```bash
curl -X PATCH https://sandbox-api.paddle.com/settings/statement-descriptor \
  -H "Authorization: Bearer $SELLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "AeroEdit" }'
```

The final descriptor is formatted as `PADDLE* {name}` (for example `PADDLE* AeroEdit`); PayPal uses `paypal_override` (for example `PAYPAL *PADDLE.NET`). Validate `name` before sending:

- **Length:** 2–10 characters.
- **Allowed characters:** letters, digits, period, space. No other punctuation — `O'BRIEN` is rejected for the apostrophe.
- **Must contain at least one letter.** Pure-digit values are rejected.

Default this from the seller's app name during onboarding, and confirm the final statement text with the seller as part of go-live.

## 3. Enable payment methods — `PATCH /settings/payment-methods` (optional)

As a merchant of record, Paddle lets you turn [digital wallets and local payment methods](/concepts/payment-methods) on or off with no integration changes and no separate payment-provider accounts. Enable all supported methods by default for the best conversion.

```bash
curl -X PATCH https://sandbox-api.paddle.com/settings/payment-methods \
  -H "Authorization: Bearer $SELLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "card": { "enabled_for_checkout": true },
    "apple_pay": { "enabled_for_checkout": true },
    "google_pay": { "enabled_for_checkout": true },
    "paypal": { "enabled_for_checkout": true }
  }'
```

Send the full set of methods you want available (the example is trimmed). [Apple Pay](/concepts/payment-methods/apple-pay) also supports domain verification, which removes a step at checkout — do that during go-live as part of [domain approval](/partners/embed-billing/seller-go-live/checkout-domains).

## Common pitfalls

- **Setting `default_checkout_url` on live before the domain is approved.** Live checkout will fail. Set the sandbox link during onboarding; set the live link during go-live.
- **Invalid statement descriptor.** Punctuation (apostrophes, ampersands) and pure-digit names are rejected — validate before sending.
- **Configuring only one environment.** Sync settings to both sandbox and live.

## Verify

- Each `PATCH` returns `200` with the updated settings.
- With a sandbox default payment link set, a checkout opens for the seller instead of erroring with "Something went wrong."

## Related docs

- [Configure account settings](/partners/embed-billing/onboard-sellers/configure-account)
- [Create a seller account](/partners/embed-billing/onboard-sellers/create-seller)
- [Register checkout domains](/partners/embed-billing/seller-go-live/checkout-domains) (setting the live default payment link)
- [`partner-api-basics`](/partners/embed-billing/get-started/api-basics)