Charge your default card for all your subscriptions

Switches every running, card-charged subscription of the signed-in customer that charges another card to their default card (paymentMethodId, the default card they saw): from then on each charges the default card, also after the default changes again. A past-due invoice is retried with it at once. Subscriptions paid by bank transfer, ended ones and those the brand's portal settings don't let you change are left as they are. Returns the subscriptions it switched (none when every subscription already charges the default card). Customer portal only (portal:write).

At a glance

REST: POST /api/v1/portal/me/payment_methods/{paymentMethodId}/use_for_subscriptions
MCP tool: portal_payment_methods_use_for_subscriptions
Operation ID: portal.payment_methods.use_for_subscriptions
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: M13

Request

Path parameters

Field	Type	Description
`paymentMethodId`	`pm_…` ID	Your default card (`pm_…`), as you saw it.

Body

This operation takes no body.

Response

200 OK with a JSON object:

Field	Type	Description
`object`	`"list"`
`data`	array of object
`data[].id`	`sub_…` ID
`data[].object`	`"portal_subscription"`
`data[].status`	one of `incomplete`, `incomplete_expired`, `trialing`, `active`, `past_due`, `unpaid`, `paused`, `canceled`
`data[].currency`	string
`data[].items`	array of object
`data[].items[].priceId`	`price_…` ID
`data[].items[].productId`	`prod_…` ID
`data[].items[].productName`	string
`data[].items[].priceName`	string or null	The price's nickname, e.g. “Pro, monthly”.
`data[].items[].interval`	object
`data[].items[].interval.interval`	one of `day`, `week`, `month`, `year`
`data[].items[].interval.intervalCount`	integer
`data[].items[].usageType`	one of `licensed`, `metered`
`data[].items[].unitAmount`	money or null	A per-unit price's amount per unit and period (null for tiered and metered prices).
`data[].items[].taxBehavior`	one of `inclusive`, `exclusive`	`exclusive`: tax is added on the invoice.
`data[].items[].id`	`si_…` ID
`data[].items[].quantity`	integer
`data[].items[].amount`	money or null	The item's full-period amount at its quantity, before discounts (null for metered items).
`data[].collectionMethod`	one of `charge_automatically`, `send_invoice`	`charge_automatically` (your card is charged) or `send_invoice` (paid by bank transfer).
`data[].paymentMethodId`	`pm_…` ID or null	The card this subscription charges (null: your default card).
`data[].currentPeriodStart`	date-time
`data[].currentPeriodEnd`	date-time
`data[].trialEnd`	date-time or null
`data[].cancelAtPeriodEnd`	boolean
`data[].cancelAt`	date-time or null
`data[].canceledAt`	date-time or null
`data[].endedAt`	date-time or null
`data[].cancellation`	object or null
`data[].discounts`	array of object
`data[].discounts[].id`	`disc_…` ID
`data[].discounts[].name`	string	The coupon's name.
`data[].discounts[].percentOffPpm`	string or null	Parts per million as a string (20% = "200000").
`data[].discounts[].amountOff`	money or null
`data[].discounts[].start`	date-time
`data[].discounts[].end`	date-time or null	When it stops applying (null: for as long as the subscription runs).
`data[].scheduledChange`	object or null	A change that applies at `effectiveAt` (a downgrade waits for the period end).
`data[].actions`	object	What you can do with this subscription now, as the brand's portal settings allow.
`data[].actions.switch_plan`	boolean
`data[].actions.change_quantity`	boolean
`data[].actions.apply_promotion_code`	boolean
`data[].actions.cancel`	boolean
`data[].actions.reactivate`	boolean
`data[].actions.change_payment_method`	boolean
`data[].cancelBehavior`	one of `period_end`, `immediate`	How cancelling here ends the subscription.
`data[].collectCancelReason`	boolean	Cancelling asks why (optional answers).
`data[].version`	integer	Send it back as `expectedVersion` to change what you saw.
`data[].createdAt`	date-time

Examples

Use the card you just added for your subscriptions

HTTP

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

Response (200):

JSON

{
  "object": "list",
  "data": [
    {
      "id": "sub_01m4tx5nj8emwbyf7y9vcf48c0",
      "object": "portal_subscription",
      "status": "active",
      "currency": "EUR",
      "items": [
        {
          "priceId": "price_01m4tx5nj8emwbyf7y9vcf48c2",
          "productId": "prod_01m4tx5nj8emwbyf7y9vcf48c4",
          "productName": "Genno Plus",
          "priceName": "Plus, monthly",
          "interval": {
            "interval": "month",
            "intervalCount": 1
          },
          "usageType": "licensed",
          "unitAmount": {
            "amount": "9000000",
            "currency": "EUR"
          },
          "taxBehavior": "inclusive",
          "id": "si_01m4tx5nj8emwbyf7y9vcf48c1",
          "quantity": 1,
          "amount": {
            "amount": "9000000",
            "currency": "EUR"
          }
        }
      ],
      "collectionMethod": "charge_automatically",
      "paymentMethodId": null,
      "currentPeriodStart": "2026-10-20T09:00:00.000Z",
      "currentPeriodEnd": "2026-11-20T10:00:00.000Z",
      "trialEnd": null,
      "cancelAtPeriodEnd": false,
      "cancelAt": null,
      "canceledAt": null,
      "endedAt": null,
      "cancellation": null,
      "discounts": [],
      "scheduledChange": null,
      "actions": {
        "switch_plan": true,
        "change_quantity": false,
        "apply_promotion_code": true,
        "cancel": true,
        "reactivate": false,
        "change_payment_method": true
      },
      "cancelBehavior": "period_end",
      "collectCancelReason": true,
      "version": 5,
      "createdAt": "2026-09-20T09:00:00.000Z"
    }
  ]
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	The payment method's ID is malformed.	Fix the fields listed in `details.issues` and send the request again.
`subscription_payment_method_invalid`	400	The card isn't your default card (any more), or it was removed: reload your payment methods.	Use a saved payment method (`pm_…`) of the subscription's customer that isn't detached, or leave it out to use the customer's default.
`version_conflict`	409	One of your subscriptions 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 subscription and wallet 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, resource_not_found, 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 card you just added for your subscriptions#

Errors#