# Make a payment method your default

> The portal.payment_methods.set_default operation: POST /api/v1/portal/me/payment_methods/{paymentMethodId}/set_default in the REST API and the portal_payment_methods_set_default tool in the MCP server.

Makes one of the signed-in customer's saved payment methods the default: subscriptions that don't name their own
method charge it from now on, and a past-due invoice is retried with it at once. Customer portal only
(`portal:write`).

## At a glance

- **REST:** `POST /api/v1/portal/me/payment_methods/{paymentMethodId}/set_default`
- **MCP tool:** `portal_payment_methods_set_default`
- **Operation ID:** `portal.payment_methods.set_default`
- **Scope:** Brand
- **Permission:** `portal:write`
- **Risk tier:** `write`
- **Dry run:** Not supported
- **Idempotency:** `Idempotency-Key` required
- **Modes:** Test and live
- **Authentication:** A customer signed in to the customer portal (API keys can't call it)
- **Since:** M9

## Request

### Path parameters

| Field             | Type      | Description                                 |
| ----------------- | --------- | ------------------------------------------- |
| `paymentMethodId` | `pm_…` ID | One of your saved payment methods (`pm_…`). |

### Body

This operation takes no body.

## Response

`200 OK` with a JSON object:

| Field       | Type                      | Description |
| ----------- | ------------------------- | ----------- |
| `id`        | `pm_…` ID                 |             |
| `object`    | `"portal_payment_method"` |             |
| `type`      | string                    |             |
| `card`      | object or null            |             |
| `isDefault` | boolean                   |             |
| `createdAt` | date-time                 |             |

## Examples

### Use the new card

```http
POST /api/v1/portal/me/payment_methods/pm_01m4tx5nj8emwbyf7y9vcf48b6/set_default
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
```

Response (`200`):

```json
{
  "id": "pm_01m4tx5nj8emwbyf7y9vcf48b6",
  "object": "portal_payment_method",
  "type": "card",
  "card": {
    "brand": "visa",
    "last4": "4242",
    "expMonth": 12,
    "expYear": 2029,
    "country": "DE"
  },
  "isDefault": true,
  "createdAt": "2026-10-20T09:00:00.000Z"
}
```

## Errors

| Code                                                                                         | HTTP status | When                                                                                                               | What to do                                                                                                                  |
| -------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed)       | 400         | The payment method's ID or another field is malformed.                                                             | Fix the fields listed in `details.issues` and send the request again.                                                       |
| [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found)     | 404         | You have no such payment method (another customer's reads the same).                                               | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.                        |
| [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict)         | 409         | Your payment methods changed at the same moment; retry.                                                            | Fetch the object again and retry the change.                                                                                |
| [`livemode_not_allowed`](https://ownrecord.io/docs/reference/errors.md#livemode_not_allowed) | 403         | The portal session is in the other mode than the request.                                                          | Use test mode, or credentials for the target's mode. Developers need live access granted by an organization owner or admin. |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied)       | 403         | The caller isn't a customer signed in to this brand's portal (operators and API keys use the customer operations). | Ask an organization owner or admin for a role or scope that allows this action.                                             |

It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`invalid_json`](https://ownrecord.io/docs/reference/errors.md#invalid_json), [`unsupported_media_type`](https://ownrecord.io/docs/reference/errors.md#unsupported_media_type), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required), [`idempotency_key_required`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_required), [`idempotency_key_reused`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_reused), [`idempotency_in_progress`](https://ownrecord.io/docs/reference/errors.md#idempotency_in_progress), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).