Make a payment method the default

Makes a saved payment method its customer's default: subscriptions that don't name their own method charge it from now on. The previous default stays saved. Detached methods can't be the default. Emits payment_method.updated for both.

At a glance

REST: POST /api/v1/payment_methods/{id}/set_default
MCP tool: payment_methods_set_default
Operation ID: payment_methods.set_default
Scope: Brand
Permission: customers:write
Risk tier: write
Dry run: Supported (send Ownrecord-Dry-Run: true)
Idempotency: Idempotency-Key required
Modes: Test and live
Authentication: API key with the customers:write scope
Since: M5

Request

Path parameters

Field	Type	Description
`id`	`pm_…` ID

Body

This operation takes no body.

Response

200 OK with a JSON object:

Field	Type	Description
`id`	`pm_…` ID
`object`	`"payment_method"`
`livemode`	boolean
`brandId`	`brd_…` ID
`customerId`	`cus_…` ID
`processor`	one of `stripe`, `mollie`, `fake`
`processorConnectionId`	`pcon_…` ID
`processorRef`	object
`processorRef.paymentMethodId`	string	The processor's ID of the method (Stripe `pm_…`).
`type`	string	`card`, `sepa_debit`, … as the processor reports it.
`card`	object or null
`isDefault`	boolean	Charged for the customer's subscriptions unless one names another.
`source`	one of `checkout`, `setup`
`createdAt`	date-time
`detachedAt`	date-time or null

Examples

Use the new card

HTTP

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

Response (200):

JSON

{
  "id": "pm_01m4tx5nj8emwbyf7y9vcf47ze",
  "object": "payment_method",
  "livemode": false,
  "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
  "customerId": "cus_01m4tx5nj8emwbyf7y9vcf47z4",
  "processor": "stripe",
  "processorConnectionId": "pcon_01m4tx5nj8emwbyf7y9vcf47zf",
  "processorRef": {
    "paymentMethodId": "pm_1QExampleCard"
  },
  "type": "card",
  "card": {
    "brand": "visa",
    "last4": "4242",
    "expMonth": 12,
    "expYear": 2029,
    "country": "DE"
  },
  "isDefault": true,
  "source": "checkout",
  "createdAt": "2026-10-13T12:00:00.000Z",
  "detachedAt": null
}

Errors

Code	HTTP status	When	What to do
`resource_not_found`	404	No payment method with this ID is visible to the request.	Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.
`version_conflict`	409	The customer's methods changed at the same time; retry.	Fetch the object again and retry the change.
`permission_denied`	403	You can't change this brand's customers (`customers:write`).	Ask an organization owner or admin for a role or scope that allows this action.
`payment_method_detached`	409	The payment method was detached.	Ask the customer to add a payment method again (a checkout in `setup` mode).

It can also return these common errors: validation_failed, api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, scope_required, idempotency_key_required, idempotency_key_reused, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Body#

Response#

Examples#

Use the new card#

Errors#