> ## Documentation Index
> Fetch the complete documentation index at: https://dodopayments-mintlify-external-integration-datafast-autosen.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Payment Method

> Update the payment method for an existing subscription. You can either add a new payment method or use an existing one from the customer's saved payment methods.

Update the payment method for a subscription. This endpoint supports both active subscriptions and subscriptions in `on_hold` state.

<Info>
  For subscriptions in `on_hold` state, updating the payment method automatically creates a charge for remaining dues, generates an invoice, and reactivates the subscription to `active` state upon successful payment.
</Info>

### Use Cases

* **Active subscriptions**: Update payment method when a card expires or customer wants to use a different payment method
* **On hold subscriptions**: Reactivate subscriptions that went on hold due to failed payments by updating the payment method
* **Payment method management**: Switch between saved payment methods or add new ones

<Info>
  To list existing payment methods for a customer, use the [List Payment Methods API](/api-reference/customers/get-customer-payment-methods). This helps you retrieve available payment method IDs when using `type: "existing"` to update a subscription's payment method.
</Info>

### Behavior for Active Subscriptions

When updating the payment method for an active subscription:

* The payment method is updated immediately
* No charge is created
* The subscription remains active
* Future renewals will use the new payment method

### Behavior for On Hold Subscriptions

When updating the payment method for a subscription in `on_hold` state:

1. A charge is automatically created for remaining dues
2. An invoice is generated for the charge
3. The payment is processed using the new payment method
4. Upon successful payment, the subscription is reactivated to `active` state
5. You'll receive webhook events: `payment.succeeded` followed by `subscription.active`

<Warning>
  If the payment fails after updating the payment method for an `on_hold` subscription, the subscription will remain in `on_hold` state. Monitor webhook events to track payment status.
</Warning>

### Webhook Events

When updating a payment method for an `on_hold` subscription, you'll receive the following webhook events:

1. **`payment.succeeded`** - The charge for remaining dues was successful
2. **`subscription.active`** - The subscription has been reactivated


## OpenAPI

````yaml post /subscriptions/{subscription_id}/update-payment-method
openapi: 3.1.0
info:
  title: public
  description: ''
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: 1.61.5
servers:
  - url: https://test.dodopayments.com/
    description: Test Mode Server Host
  - url: https://live.dodopayments.com/
    description: Live Mode Server Host
security: []
tags:
  - name: Products
  - name: Payments
  - name: Subscriptions
  - name: Addons
  - name: Customers
  - name: Refunds
  - name: Disputes
  - name: Events
  - name: License Keys
  - name: Licenses
  - name: Discounts
  - name: Meters
  - name: Outgoing Webhooks
  - name: Checkout
  - name: Webhook Events
paths:
  /subscriptions/{subscription_id}/update-payment-method:
    post:
      tags:
        - Subscriptions
      operationId: update
      parameters:
        - name: subscription_id
          in: path
          description: Subscription Id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePaymentMethodReq'
        required: true
      responses:
        '200':
          description: Payment method updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdatePaymentMethodResponse'
        '422':
          description: Invalid Request Object or Parameters
        '500':
          description: Something went wrong :(
      security:
        - API_KEY: []
      x-codeSamples:
        - lang: JavaScript
          source: >-
            import DodoPayments from 'dodopayments';


            const client = new DodoPayments({
              bearerToken: 'My Bearer Token',
            });


            const response = await
            client.subscriptions.updatePaymentMethod('subscription_id', { type:
            'new' });


            console.log(response.payment_id);
        - lang: Python
          source: |-
            from dodopayments import DodoPayments

            client = DodoPayments(
                bearer_token="My Bearer Token",
            )
            response = client.subscriptions.update_payment_method(
                subscription_id="subscription_id",
                type="new",
            )
            print(response.payment_id)
        - lang: Go
          source: |
            package main

            import (
              "context"
              "fmt"

              "github.com/dodopayments/dodopayments-go"
              "github.com/dodopayments/dodopayments-go/option"
            )

            func main() {
              client := dodopayments.NewClient(
                option.WithBearerToken("My Bearer Token"),
              )
              response, err := client.Subscriptions.UpdatePaymentMethod(
                context.TODO(),
                "subscription_id",
                dodopayments.SubscriptionUpdatePaymentMethodParams{
                  Body: dodopayments.SubscriptionUpdatePaymentMethodParamsBodyNew{
                    Type: dodopayments.F(dodopayments.SubscriptionUpdatePaymentMethodParamsBodyNewTypeNew),
                  },
                },
              )
              if err != nil {
                panic(err.Error())
              }
              fmt.Printf("%+v\n", response.PaymentID)
            }
        - lang: Java
          source: >-
            package com.dodopayments.api.example;


            import com.dodopayments.api.client.DodoPaymentsClient;

            import com.dodopayments.api.client.okhttp.DodoPaymentsOkHttpClient;

            import
            com.dodopayments.api.models.subscriptions.SubscriptionUpdatePaymentMethodParams;

            import
            com.dodopayments.api.models.subscriptions.SubscriptionUpdatePaymentMethodResponse;


            public final class Main {
                private Main() {}

                public static void main(String[] args) {
                    DodoPaymentsClient client = DodoPaymentsOkHttpClient.fromEnv();

                    SubscriptionUpdatePaymentMethodParams params = SubscriptionUpdatePaymentMethodParams.builder()
                        .subscriptionId("subscription_id")
                        .body(SubscriptionUpdatePaymentMethodParams.Body.New.builder()
                            .type(SubscriptionUpdatePaymentMethodParams.Body.New.Type.NEW)
                            .build())
                        .build();
                    SubscriptionUpdatePaymentMethodResponse response = client.subscriptions().updatePaymentMethod(params);
                }
            }
        - lang: Kotlin
          source: >-
            package com.dodopayments.api.example


            import com.dodopayments.api.client.DodoPaymentsClient

            import com.dodopayments.api.client.okhttp.DodoPaymentsOkHttpClient

            import
            com.dodopayments.api.models.subscriptions.SubscriptionUpdatePaymentMethodParams

            import
            com.dodopayments.api.models.subscriptions.SubscriptionUpdatePaymentMethodResponse


            fun main() {
                val client: DodoPaymentsClient = DodoPaymentsOkHttpClient.fromEnv()

                val params: SubscriptionUpdatePaymentMethodParams = SubscriptionUpdatePaymentMethodParams.builder()
                    .subscriptionId("subscription_id")
                    .body(SubscriptionUpdatePaymentMethodParams.Body.New.builder()
                        .type(SubscriptionUpdatePaymentMethodParams.Body.New.Type.NEW)
                        .build())
                    .build()
                val response: SubscriptionUpdatePaymentMethodResponse = client.subscriptions().updatePaymentMethod(params)
            }
        - lang: Ruby
          source: |-
            require "dodopayments"

            dodo_payments = Dodopayments::Client.new(
              bearer_token: "My Bearer Token",
              environment: "test_mode" # defaults to "live_mode"
            )

            response = dodo_payments.subscriptions.update_payment_method(
              "subscription_id",
              payment_method_id: "payment_method_id",
              type: :existing
            )

            puts(response)
components:
  schemas:
    UpdatePaymentMethodReq:
      oneOf:
        - type: object
          title: New
          required:
            - type
          properties:
            return_url:
              type:
                - string
                - 'null'
            type:
              type: string
              enum:
                - new
        - type: object
          title: Existing
          required:
            - payment_method_id
            - type
          properties:
            payment_method_id:
              type: string
            type:
              type: string
              enum:
                - existing
    UpdatePaymentMethodResponse:
      type: object
      properties:
        client_secret:
          type:
            - string
            - 'null'
        expires_on:
          type:
            - string
            - 'null'
          format: date-time
        payment_id:
          type:
            - string
            - 'null'
        payment_link:
          type:
            - string
            - 'null'
  securitySchemes:
    API_KEY:
      type: http
      scheme: bearer

````