Make a payment method your default

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`	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`	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`	409	Your payment methods changed at the same moment; retry.	Fetch the object again and retry the change.
`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`	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: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, scope_required, idempotency_key_required, idempotency_key_reused, idempotency_in_progress, dry_run_not_supported, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Body#

Response#

Examples#

Use the new card#

Errors#