> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# Update payment details

Build a workflow for updating customer payment details for a subscription using the Paddle API and Paddle.js.

---

It's good practice to give customers a way to change the payment method that they use to pay for future subscription renewals and charges. It's especially important where subscriptions are past due, meaning customers have an outstanding payment.

Payment methods can be updated for automatically-collected subscriptions that are active or past due.

{% callout type="info" %}
This guide walks through updating details for an existing subscription. To present saved payment methods at checkout for new purchases, see [Present saved payment methods at checkout](https://developer.paddle.com/build/checkout/saved-payment-methods.md)
{% /callout %}

## How it works

When payment fails for an automatically-collected [subscription](https://developer.paddle.com/api-reference/subscriptions/overview.md), the subscription status changes to `past_due`. Paddle works to automatically recover the payment for you by automatically retrying the payment method associated with that subscription, using algorithms to retry payments at the best time for success.

{% callout type="note" %}
[Turn on Payment Recovery](https://developer.paddle.com/build/retain/set-up-retain-profitwell.md), part of Paddle Retain, to get more comprehensive payment recovery and control over the experience, including payment reminders by email, in-app, and by SMS.
{% /callout %}

You can build a workflow to let a customer update their payment details using [Paddle Checkout](https://developer.paddle.com/concepts/sell/self-serve-checkout.md), which handles securely capturing card details or payment using [another payment method](https://developer.paddle.com/concepts/payment-methods/overview.md).

To open Paddle Checkout for an existing subscription, you need a transaction for that subscription. You can use [the get a transaction to update payment method operation](https://developer.paddle.com/api-reference/subscriptions/update-payment-method.md) to get a transaction that you can [pass to Paddle.js](https://developer.paddle.com/build/transactions/pass-transaction-checkout.md) to open a Paddle Checkout for it.

The returned [transaction](https://developer.paddle.com/api-reference/transactions/overview.md) depends on the `status` of the related subscription:

{% feature-comparison level=3 %}

{% feature-column title="Past due subscription" %}

{% feature-item %}
When the subscription status is `past_due`, the last `past_due` transaction is returned.
{% /feature-item %}

{% feature-item title="Overlay checkout" %}
Displays the items and totals for the overdue transaction, so that customers know they'll be charged when they update their details.
{% /feature-item %}

{% feature-item title="Inline checkout" %}
Includes an "Update payment method" button letting customers update payment details and pay the overdue amount.
{% /feature-item %}

{% /feature-column %}

{% feature-column title="Active subscription" %}

{% feature-item %}
When the subscription status is `active`, Paddle creates a zero-value transaction for the subscription's items.
{% /feature-item %}

{% feature-item title="Overlay checkout" %}
Displays the subscription's items and shows a message indicating the customer is updating their payment details, with no charge due.
{% /feature-item %}

{% feature-item title="Inline checkout" %}
Includes an "Update payment method" button letting customers update their details without making a payment.
{% /feature-item %}

{% /feature-column %}

{% /feature-comparison %}

When the checkout for the returned transaction completes, Paddle saves the updated payment details and uses them for future renewals and charges.

## Before you begin

{% callout type="info" %}
You can't make changes to a subscription if the next billing period is within 30 minutes, or the subscription status is `past_due`.
{% /callout %}

To update payment details for a subscription, you'll need to [get the subscription ID](https://developer.paddle.com/api-reference/subscriptions/list-subscriptions.md) for the subscription you want to change.

You can use the `status` query parameter when listing with the value `active,past_due` to get a list of active and past due subscriptions.

To pass a payment method update transaction to a checkout, you'll need [a page that includes Paddle.js](https://developer.paddle.com/paddlejs/include-paddlejs.md). This is typically [your default payment link](https://developer.paddle.com/build/transactions/default-payment-link.md).

If you haven't already, you'll need to:

- Add [a default payment link](https://developer.paddle.com/build/transactions/default-payment-link.md) to your checkout under **Paddle > Checkout > Checkout settings > Default payment link**.
- Get your default payment link [domain approved](https://www.paddle.com/help/start/account-verification/what-is-domain-verification) if you're working with the live environment.

## Use the portal {% badge label="Recommended" variant="outline" /%}

The quickest way to let customers update payment details is to link them to [the customer portal](https://developer.paddle.com/concepts/customer-portal.md). The portal is hosted by Paddle and handles the checkout flow for capturing card details (or other payment methods) out of the box, so you don't need to build your own UI with Paddle.js.

When customers update their payment method using the portal, Paddle saves the new details and uses them for future renewals and charges.

You can link customers to the portal in two ways:

- **Customer portal session**  
  Generates an authenticated, deep link straight to the payment method update page for a specific subscription. Customers don't need to sign in to the portal.
- **Subscription management URL**  
  A pre-generated link returned on the subscription entity. Quickest to integrate, but customers will need to sign in to the portal using their email address.

### With a customer portal session

Generate a customer portal session for the customer and pass the `subscription_ids` of the subscriptions you want to create deep links for. Paddle returns an authenticated `update_subscription_payment_method` link for each subscription that you can present in your app.

Use a customer portal session when customers are already signed in to your app, so they don't have to sign in to the portal again.

{% api-example method="POST" path="/customers/{customer_id}/portal-sessions" href="/api-reference/customer-portals/create-portal-session" %}

```json
{
  "subscription_ids": [
    "sub_01jcgfqad406rsfjcgq44g9djq",
    "sub_01jcdafvpe5hm4vczfefsbwhvp"
  ]
}
```

```json
{
  "data": {
    "id": "cpls_01jcggxbs9b4tff8zy7kfwwr1s",
    "customer_id": "ctm_01jcdaf4zgm2fxw3nc0e4fn137",
    "urls": {
      "general": {
        "overview": "https://customer-portal.paddle.com/cpl_01gsx07ferwf96qnjz1mrc6h0q?action=overview&token=pga_eyJhbGciOiJFZERTQSIsImtpZCI6Imp3a18wMWhkazBuOHF3OG55NTJ5cGNocGNhazA1ayIsInR5cCI6IkpXVCJ9.eyJpZCI6InBnYV8wMWpjZ2d4YnNmNTEzcGY1MjZyNjZrbTMxOSIsInNlbGxlci1pZCI6IjEwODg5IiwidHlwZSI6InN0YW5kYXJkIiwidmVyc2lvbiI6IjEiLCJ1c2FnZSI6ImN1c3RvbWVyLXBvcnRhbC1zZXNzaW9uIiwic2NvcGUiOiJjdXN0b21lci5jaGVja291dC5jcmVhdGUgY3VzdG9tZXIuY2hlY2tvdXQucmVhZCBjdXN0b21lci5jdXN0b21lci5yZWFkIGN1c3RvbWVyLmN1c3RvbWVyLnVwZGF0ZSBjdXN0b21lci5jdXN0b21lci1hZGRyZXNzLnJlYWQgY3VzdG9tZXIuY3VzdG9tZXItcGF5bWVudC1tZXRob2QucmVhZCBjdXN0b21lci5jdXN0b21lci1wYXltZW50LW1ldGhvZC5kZWxldGUgY3VzdG9tZXIuaW52b2ljZS5yZWFkIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi1jYW5jZWwuY3JlYXRlIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi1wYXltZW50LnJlYWQgY3VzdG9tZXIuc3Vic2NyaXB0aW9uLXBheW1lbnQudXBkYXRlIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi5yZWFkIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi51cGRhdGUgY3VzdG9tZXIudHJhbnNhY3Rpb24ucmVhZCBjdXN0b21lci50cmFuc2FjdGlvbi5vcmlnaW4ucmVhZCIsImlzcyI6Imd1ZXN0YWNjZXNzLXNlcnZpY2UiLCJzdWIiOiJjdG1fMDFqY2RhZjR6Z20yZnh3M25jMGU0Zm4xMzciLCJleHAiOjE3MzE1MTI4MzAsImlhdCI6MTczMTQyNjQzMH0.DHHFoLwIDWCt9F9hZmGTG3G-uhi9tUltTbMSY6Nf-vVplemJYrcC_PyF97Wm88bmHEO1f8LL3agMYNFDwvzADw"
      },
      "subscriptions": [
        {
          "id": "sub_01jcgfqad406rsfjcgq44g9djq",
          "cancel_subscription": "https://customer-portal.paddle.com/cpl_01gsx07ferwf96qnjz1mrc6h0q?action=cancel_subscription&subscription_id=sub_01jcgfqad406rsfjcgq44g9djq&token=pga_eyJhbGciOiJFZERTQSIsImtpZCI6Imp3a18wMWhkazBuOHF3OG55NTJ5cGNocGNhazA1ayIsInR5cCI6IkpXVCJ9.eyJpZCI6InBnYV8wMWpjZ2d4YnNmNTEzcGY1MjZyNjZrbTMxOSIsInNlbGxlci1pZCI6IjEwODg5IiwidHlwZSI6InN0YW5kYXJkIiwidmVyc2lvbiI6IjEiLCJ1c2FnZSI6ImN1c3RvbWVyLXBvcnRhbC1zZXNzaW9uIiwic2NvcGUiOiJjdXN0b21lci5jaGVja291dC5jcmVhdGUgY3VzdG9tZXIuY2hlY2tvdXQucmVhZCBjdXN0b21lci5jdXN0b21lci5yZWFkIGN1c3RvbWVyLmN1c3RvbWVyLnVwZGF0ZSBjdXN0b21lci5jdXN0b21lci1hZGRyZXNzLnJlYWQgY3VzdG9tZXIuY3VzdG9tZXItcGF5bWVudC1tZXRob2QucmVhZCBjdXN0b21lci5jdXN0b21lci1wYXltZW50LW1ldGhvZC5kZWxldGUgY3VzdG9tZXIuaW52b2ljZS5yZWFkIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi1jYW5jZWwuY3JlYXRlIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi1wYXltZW50LnJlYWQgY3VzdG9tZXIuc3Vic2NyaXB0aW9uLXBheW1lbnQudXBkYXRlIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi5yZWFkIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi51cGRhdGUgY3VzdG9tZXIudHJhbnNhY3Rpb24ucmVhZCBjdXN0b21lci50cmFuc2FjdGlvbi5vcmlnaW4ucmVhZCIsImlzcyI6Imd1ZXN0YWNjZXNzLXNlcnZpY2UiLCJzdWIiOiJjdG1fMDFqY2RhZjR6Z20yZnh3M25jMGU0Zm4xMzciLCJleHAiOjE3MzE1MTI4MzAsImlhdCI6MTczMTQyNjQzMH0.DHHFoLwIDWCt9F9hZmGTG3G-uhi9tUltTbMSY6Nf-vVplemJYrcC_PyF97Wm88bmHEO1f8LL3agMYNFDwvzADw",
          "update_subscription_payment_method": "https://customer-portal.paddle.com/cpl_01gsx07ferwf96qnjz1mrc6h0q?action=update_subscription_payment_method&subscription_id=sub_01jcgfqad406rsfjcgq44g9djq&token=pga_eyJhbGciOiJFZERTQSIsImtpZCI6Imp3a18wMWhkazBuOHF3OG55NTJ5cGNocGNhazA1ayIsInR5cCI6IkpXVCJ9.eyJpZCI6InBnYV8wMWpjZ2d4YnNmNTEzcGY1MjZyNjZrbTMxOSIsInNlbGxlci1pZCI6IjEwODg5IiwidHlwZSI6InN0YW5kYXJkIiwidmVyc2lvbiI6IjEiLCJ1c2FnZSI6ImN1c3RvbWVyLXBvcnRhbC1zZXNzaW9uIiwic2NvcGUiOiJjdXN0b21lci5jaGVja291dC5jcmVhdGUgY3VzdG9tZXIuY2hlY2tvdXQucmVhZCBjdXN0b21lci5jdXN0b21lci5yZWFkIGN1c3RvbWVyLmN1c3RvbWVyLnVwZGF0ZSBjdXN0b21lci5jdXN0b21lci1hZGRyZXNzLnJlYWQgY3VzdG9tZXIuY3VzdG9tZXItcGF5bWVudC1tZXRob2QucmVhZCBjdXN0b21lci5jdXN0b21lci1wYXltZW50LW1ldGhvZC5kZWxldGUgY3VzdG9tZXIuaW52b2ljZS5yZWFkIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi1jYW5jZWwuY3JlYXRlIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi1wYXltZW50LnJlYWQgY3VzdG9tZXIuc3Vic2NyaXB0aW9uLXBheW1lbnQudXBkYXRlIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi5yZWFkIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi51cGRhdGUgY3VzdG9tZXIudHJhbnNhY3Rpb24ucmVhZCBjdXN0b21lci50cmFuc2FjdGlvbi5vcmlnaW4ucmVhZCIsImlzcyI6Imd1ZXN0YWNjZXNzLXNlcnZpY2UiLCJzdWIiOiJjdG1fMDFqY2RhZjR6Z20yZnh3M25jMGU0Zm4xMzciLCJleHAiOjE3MzE1MTI4MzAsImlhdCI6MTczMTQyNjQzMH0.DHHFoLwIDWCt9F9hZmGTG3G-uhi9tUltTbMSY6Nf-vVplemJYrcC_PyF97Wm88bmHEO1f8LL3agMYNFDwvzADw"
        },
        {
          "id": "sub_01jcdafvpe5hm4vczfefsbwhvp",
          "cancel_subscription": "https://customer-portal.paddle.com/cpl_01gsx07ferwf96qnjz1mrc6h0q?action=cancel_subscription&subscription_id=sub_01jcdafvpe5hm4vczfefsbwhvp&token=pga_eyJhbGciOiJFZERTQSIsImtpZCI6Imp3a18wMWhkazBuOHF3OG55NTJ5cGNocGNhazA1ayIsInR5cCI6IkpXVCJ9.eyJpZCI6InBnYV8wMWpjZ2d4YnNmNTEzcGY1MjZyNjZrbTMxOSIsInNlbGxlci1pZCI6IjEwODg5IiwidHlwZSI6InN0YW5kYXJkIiwidmVyc2lvbiI6IjEiLCJ1c2FnZSI6ImN1c3RvbWVyLXBvcnRhbC1zZXNzaW9uIiwic2NvcGUiOiJjdXN0b21lci5jaGVja291dC5jcmVhdGUgY3VzdG9tZXIuY2hlY2tvdXQucmVhZCBjdXN0b21lci5jdXN0b21lci5yZWFkIGN1c3RvbWVyLmN1c3RvbWVyLnVwZGF0ZSBjdXN0b21lci5jdXN0b21lci1hZGRyZXNzLnJlYWQgY3VzdG9tZXIuY3VzdG9tZXItcGF5bWVudC1tZXRob2QucmVhZCBjdXN0b21lci5jdXN0b21lci1wYXltZW50LW1ldGhvZC5kZWxldGUgY3VzdG9tZXIuaW52b2ljZS5yZWFkIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi1jYW5jZWwuY3JlYXRlIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi1wYXltZW50LnJlYWQgY3VzdG9tZXIuc3Vic2NyaXB0aW9uLXBheW1lbnQudXBkYXRlIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi5yZWFkIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi51cGRhdGUgY3VzdG9tZXIudHJhbnNhY3Rpb24ucmVhZCBjdXN0b21lci50cmFuc2FjdGlvbi5vcmlnaW4ucmVhZCIsImlzcyI6Imd1ZXN0YWNjZXNzLXNlcnZpY2UiLCJzdWIiOiJjdG1fMDFqY2RhZjR6Z20yZnh3M25jMGU0Zm4xMzciLCJleHAiOjE3MzE1MTI4MzAsImlhdCI6MTczMTQyNjQzMH0.DHHFoLwIDWCt9F9hZmGTG3G-uhi9tUltTbMSY6Nf-vVplemJYrcC_PyF97Wm88bmHEO1f8LL3agMYNFDwvzADw",
          "update_subscription_payment_method": "https://customer-portal.paddle.com/cpl_01gsx07ferwf96qnjz1mrc6h0q?action=update_subscription_payment_method&subscription_id=sub_01jcdafvpe5hm4vczfefsbwhvp&token=pga_eyJhbGciOiJFZERTQSIsImtpZCI6Imp3a18wMWhkazBuOHF3OG55NTJ5cGNocGNhazA1ayIsInR5cCI6IkpXVCJ9.eyJpZCI6InBnYV8wMWpjZ2d4YnNmNTEzcGY1MjZyNjZrbTMxOSIsInNlbGxlci1pZCI6IjEwODg5IiwidHlwZSI6InN0YW5kYXJkIiwidmVyc2lvbiI6IjEiLCJ1c2FnZSI6ImN1c3RvbWVyLXBvcnRhbC1zZXNzaW9uIiwic2NvcGUiOiJjdXN0b21lci5jaGVja291dC5jcmVhdGUgY3VzdG9tZXIuY2hlY2tvdXQucmVhZCBjdXN0b21lci5jdXN0b21lci5yZWFkIGN1c3RvbWVyLmN1c3RvbWVyLnVwZGF0ZSBjdXN0b21lci5jdXN0b21lci1hZGRyZXNzLnJlYWQgY3VzdG9tZXIuY3VzdG9tZXItcGF5bWVudC1tZXRob2QucmVhZCBjdXN0b21lci5jdXN0b21lci1wYXltZW50LW1ldGhvZC5kZWxldGUgY3VzdG9tZXIuaW52b2ljZS5yZWFkIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi1jYW5jZWwuY3JlYXRlIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi1wYXltZW50LnJlYWQgY3VzdG9tZXIuc3Vic2NyaXB0aW9uLXBheW1lbnQudXBkYXRlIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi5yZWFkIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi51cGRhdGUgY3VzdG9tZXIudHJhbnNhY3Rpb24ucmVhZCBjdXN0b21lci50cmFuc2FjdGlvbi5vcmlnaW4ucmVhZCIsImlzcyI6Imd1ZXN0YWNjZXNzLXNlcnZpY2UiLCJzdWIiOiJjdG1fMDFqY2RhZjR6Z20yZnh3M25jMGU0Zm4xMzciLCJleHAiOjE3MzE1MTI4MzAsImlhdCI6MTczMTQyNjQzMH0.DHHFoLwIDWCt9F9hZmGTG3G-uhi9tUltTbMSY6Nf-vVplemJYrcC_PyF97Wm88bmHEO1f8LL3agMYNFDwvzADw"
        }
      ]
    },
    "created_at": "2024-11-12T15:47:10.761048551Z"
  },
  "meta": {
    "request_id": "0936d329-68b4-4c9f-b33c-d872d3ffbaf1"
  }
}
```

{% /api-example %}

For more information, see [Use customer portal links in your app](https://developer.paddle.com/build/customers/integrate-customer-portal.md).

{% callout type="info" %}
Customer portal sessions are temporary and shouldn't be cached. Create a new customer portal session each time you want to generate authenticated links.
{% /callout %}

### With a subscription management URL

Send a `GET` request to the `/subscriptions/{subscription_id}` endpoint to get the subscription, then return `management_urls.update_payment_method` to the customer.

When customers click this link, they're taken to the customer portal where they can sign in with their email address and update their payment method.

{% api-endpoint method="GET" path="/subscriptions/{subscription_id}" href="/api-reference/subscriptions/get-subscription" /%}

{% callout type="info" %}
For security, subscription management URLs include a temporary `token` parameter. Don't store these URLs — they expire. The `management_urls` object isn't returned in events for this reason, too.
{% /callout %}

## Use the API

If you want to embed the payment method update flow into your own app rather than handing customers off to the portal, you can build a workflow using [the Paddle API](https://developer.paddle.com/api-reference/overview.md) and [Paddle.js](https://developer.paddle.com/paddlejs/overview.md). Use this approach when you want full control over the look and feel of the update flow, like presenting [an inline checkout](https://developer.paddle.com/concepts/sell/branded-integrated-inline-checkout.md) embedded in your app.

Build a payment method update workflow using the API in two steps:

1. **Get a payment method update transaction**
   Use the Paddle API to get a transaction for updating the payment method.
2. **Pass a transaction to a checkout**
   Pass the transaction to Paddle.js to open a checkout where the customer enters their new payment details.

### Get a payment method update transaction {% step=true stepReset=true %}

Send a `GET` request to the `/subscriptions/{subscription_id}/update-payment-method-transaction` endpoint to get a transaction for updating the payment method.

The transaction Paddle returns depends on the subscription status:

{% accordion %}
{% accordion-item title="Get a transaction for a past due subscription" %}

When the related subscription is `past_due`, this operation returns the last `past_due` transaction for the subscription.

If successful, Paddle returns the last `past_due` transaction for the subscription.

{% api-example method="GET" path="/subscriptions/{subscription_id}/update-payment-method-transaction" href="/api-reference/subscriptions/update-payment-method" %}

```json
{
  "data": {
    "id": "txn_01h2ast61chjbjmz9z4pvwvt0h",
    "status": "past_due",
    "customer_id": "ctm_01h2asct98zxebssbkt1q6tfyr",
    "address_id": "add_01h2asctbmeekr9364bjgjdbxe",
    "business_id": null,
    "custom_data": null,
    "origin": "subscription_recurring",
    "collection_mode": "automatic",
    "subscription_id": "sub_01h2ase3pcjyhmc25h57t7qe2e",
    "invoice_id": null,
    "invoice_number": null,
    "billing_details": null,
    "billing_period": null,
    "currency_code": "USD",
    "discount_id": null,
    "created_at": "2023-06-07T11:28:01.053056Z",
    "updated_at": "2023-06-07T11:28:04.127729Z",
    "billed_at": "2023-06-07T11:28:00.556475Z",
    "items": [
      {
        "price": {
          "id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
          "description": "Monthly (per seat)",
          "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
          "billing_cycle": {
            "interval": "month",
            "frequency": 1
          },
          "trial_period": null,
          "tax_mode": "account_setting",
          "unit_price": {
            "amount": "3000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "quantity": {
            "minimum": 10,
            "maximum": 999
          },
          "status": "active"
        },
        "quantity": 10
      },
      {
        "price": {
          "id": "pri_01h1vjfevh5etwq3rb416a23h2",
          "description": "Monthly",
          "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65",
          "billing_cycle": {
            "interval": "month",
            "frequency": 1
          },
          "trial_period": null,
          "tax_mode": "account_setting",
          "unit_price": {
            "amount": "10000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "quantity": {
            "minimum": 1,
            "maximum": 100
          },
          "status": "active"
        },
        "quantity": 1
      }
    ],
    "details": {
      "tax_rates_used": [
        {
          "tax_rate": "0.08875",
          "totals": {
            "subtotal": "40000",
            "discount": "0",
            "tax": "3549",
            "total": "43549"
          }
        }
      ],
      "totals": {
        "subtotal": "40000",
        "tax": "3549",
        "discount": "0",
        "total": "43549",
        "grand_total": "43549",
        "fee": null,
        "credit": "0",
        "balance": "43549",
        "earnings": null,
        "currency_code": "USD"
      },
      "payout_totals": null,
      "line_items": [
        {
          "id": "txnitm_01h2ast6gbyw6bfc6rsac7ts5x",
          "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
          "quantity": 10,
          "totals": {
            "subtotal": "30000",
            "tax": "2662",
            "discount": "0",
            "total": "32662"
          },
          "product": {
            "id": "pro_01gsz4t5hdjse780zja8vvr7jg",
            "name": "ChatApp Pro",
            "description": "Everything in basic, plus access to a suite of powerful tools and features designed to take your team's productivity to the next level.",
            "tax_category": "standard",
            "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/2nmP8MQSret0aWeDemRw_icon1.png",
            "status": "active"
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "3000",
            "tax": "266",
            "discount": "0",
            "total": "3266"
          }
        },
        {
          "id": "txnitm_01h2ast6gbyw6bfc6rsbhcx6b0",
          "price_id": "pri_01h1vjfevh5etwq3rb416a23h2",
          "quantity": 1,
          "totals": {
            "subtotal": "10000",
            "tax": "887",
            "discount": "0",
            "total": "10887"
          },
          "product": {
            "id": "pro_01h1vjes1y163xfj1rh1tkfb65",
            "name": "Voice rooms addon",
            "description": "Create voice rooms in your chats to work in real time alongside your colleagues. Includes unlimited voice rooms and recording backup for compliance.",
            "tax_category": "standard",
            "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/GcZzBjXRfiraensppgtQ_icon2.png",
            "status": "active"
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "10000",
            "tax": "887",
            "discount": "0",
            "total": "10887"
          }
        }
      ]
    },
    "payments": [
      {
        "payment_attempt_id": "07dc70d3-5121-4a20-ac5d-aac1469be0a4",
        "stored_payment_method_id": "0d9b786a-5c7e-461a-8346-d20d0a373dee",
        "amount": "43549",
        "status": "error",
        "error_code": "authentication_failed",
        "method_details": {
          "type": "card",
          "card": {
            "type": "visa",
            "last4": "3184",
            "expiry_month": 10,
            "expiry_year": 2025
          }
        },
        "created_at": "2023-06-07T11:28:01.233671Z",
        "captured_at": null
      }
    ],
    "checkout": {
      "url": "https://aeroedit.com/pay?_ptxn=txn_01h2ast61chjbjmz9z4pvwvt0h"
    }
  },
  "meta": {
    "request_id": "762beb6c-60c7-4297-83ca-01b1feaad36c"
  }
}
```

{% /api-example %}

{% /accordion-item %}
{% accordion-item title="Get a transaction for an active subscription" %}

When the related subscription is `active`, this operation creates a new zero-value transaction for the subscription.

Paddle creates this transaction so you can pass it to Paddle.js to open a checkout to update payment details — no charge is due, and no change is made to the subscription.

If successful, Paddle returns the new zero value transaction for this subscription.

Its origin is `subscription_payment_method_change`. All items and totals on the transaction are zero.

{% api-example method="GET" path="/subscriptions/{subscription_id}/update-payment-method-transaction" href="/api-reference/subscriptions/update-payment-method" %}

```json
{
  "data": {
    "id": "txn_01jspbekkwn03q6zp8bezp3tv2",
    "status": "ready",
    "customer_id": "ctm_01jspbafm96p2ppbe85921nf6p",
    "address_id": "add_01jspbafmrn485m030p7kx9dbr",
    "business_id": null,
    "custom_data": null,
    "origin": "subscription_payment_method_change",
    "collection_mode": "automatic",
    "subscription_id": "sub_01jspbbyjtkycfmjf7ye85yvp2",
    "invoice_id": null,
    "invoice_number": null,
    "discount_id": null,
    "billing_details": null,
    "billing_period": {
      "starts_at": "2025-04-25T11:29:46.915899Z",
      "ends_at": "2025-04-25T11:29:46.915899Z"
    },
    "currency_code": "USD",
    "created_at": "2025-04-25T11:31:14.986430069Z",
    "updated_at": "2025-04-25T11:31:14.986430069Z",
    "billed_at": null,
    "revised_at": null,
    "items": [
      {
        "price": {
          "id": "pri_01jspaymrp8mpq0fxdgwxy5vwh",
          "product_id": "pro_01jspay5m2ry6s10w1m9xfthvz",
          "type": "standard",
          "description": "Get exclusive access to our expert team of product specialists, available to help you make the most of your AeroEdit subscription.",
          "name": "AeroEdit VIP",
          "billing_cycle": {
            "interval": "month",
            "frequency": 1
          },
          "tax_mode": "account_setting",
          "unit_price": {
            "amount": "30000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "status": "active",
          "quantity": {
            "minimum": 1,
            "maximum": 1
          },
          "import_meta": null,
          "created_at": "2025-04-25T11:22:31.574394Z",
          "updated_at": "2025-04-25T11:22:31.574395Z",
          "trial_period": null
        },
        "quantity": 1,
        "proration": {
          "rate": "0",
          "billing_period": {
            "starts_at": "2025-04-25T11:29:46.915899Z",
            "ends_at": "2025-05-25T11:29:46.915899Z"
          }
        }
      }
    ],
    "details": {
      "tax_rates_used": [
        {
          "tax_rate": "0.08875",
          "totals": {
            "subtotal": "0",
            "discount": "0",
            "tax": "0",
            "total": "0"
          }
        }
      ],
      "totals": {
        "subtotal": "0",
        "tax": "0",
        "discount": "0",
        "total": "0",
        "grand_total": "0",
        "grand_total_tax": "0",
        "fee": null,
        "credit": "0",
        "currency_code": "USD",
        "balance": "0",
        "credit_to_balance": "0",
        "earnings": null
      },
      "adjusted_totals": {
        "subtotal": "0",
        "tax": "0",
        "total": "0",
        "grand_total": "0",
        "grand_total_tax": "0",
        "fee": null,
        "earnings": null,
        "currency_code": "USD",
        "retained_fee": "0"
      },
      "payout_totals": null,
      "adjusted_payout_totals": null,
      "line_items": [
        {
          "id": "txnitm_01jspbekwp0ajkz6qxj4wdmzf3",
          "price_id": "pri_01jspaymrp8mpq0fxdgwxy5vwh",
          "quantity": 1,
          "totals": {
            "subtotal": "0",
            "tax": "0",
            "discount": "0",
            "total": "0"
          },
          "product": {
            "id": "pro_01jspay5m2ry6s10w1m9xfthvz",
            "name": "AeroEdit VIP",
            "type": "standard",
            "tax_category": "standard",
            "description": "Get exclusive access to our expert team of product specialists, available to help you make the most of your AeroEdit subscription.",
            "image_url": "https://paddle.s3.amazonaws.com/user/165798/qgyipKJwRtq98YNboipo_vip-support.png",
            "custom_data": null,
            "status": "active",
            "import_meta": null,
            "created_at": "2025-04-25T11:22:16.066Z",
            "updated_at": "2025-04-25T11:22:16.066Z"
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "0",
            "discount": "0",
            "tax": "0",
            "total": "0"
          },
          "proration": {
            "rate": "0",
            "billing_period": {
              "starts_at": "2025-04-25T11:29:46.915899Z",
              "ends_at": "2025-05-25T11:29:46.915899Z"
            }
          }
        }
      ]
    },
    "payments": [],
    "checkout": {
      "url": "https://aeroedit.com/pay?_ptxn=txn_01hv8zbfzrnfr6b4hfexhk4e7h"
    },
    "customer": {
      "id": "ctm_01jspbafm96p2ppbe85921nf6p",
      "name": null,
      "email": "sam@example.com",
      "locale": "en",
      "marketing_consent": false,
      "custom_data": null,
      "status": "active",
      "created_at": "2025-04-25T11:28:59.529Z",
      "updated_at": "2025-04-25T11:28:59.529Z",
      "import_meta": null
    },
    "address": {
      "id": "add_01jspbafmrn485m030p7kx9dbr",
      "customer_id": "ctm_01jspbafm96p2ppbe85921nf6p",
      "description": null,
      "first_line": null,
      "second_line": null,
      "city": null,
      "postal_code": "10021",
      "region": null,
      "country_code": "US",
      "status": "active",
      "custom_data": null,
      "import_meta": null,
      "created_at": "2025-04-25T11:28:59.544Z",
      "updated_at": "2025-04-25T11:28:59.544Z"
    },
    "adjustments_totals": {
      "subtotal": "0",
      "tax": "0",
      "total": "0",
      "fee": "0",
      "earnings": "0",
      "breakdown": {
        "credit": "0",
        "refund": "0",
        "chargeback": "0"
      },
      "currency_code": "USD",
      "retained_fee": "0"
    },
    "available_payment_methods": ["apple_pay", "card", "paypal", "google_pay"],
    "adjustments": []
  },
  "meta": {
    "request_id": "c73663c7-7308-4af5-9cf2-4cc9f7372196"
  }
}
```

{% /api-example %}

{% /accordion-item %}
{% /accordion %}

### Pass a transaction to a checkout {% step=true %}

Once you have a payment method update transaction, pass it to [Paddle.js](https://developer.paddle.com/paddlejs/overview.md) to open a checkout for it. To do this, you can either:

- Use the `checkout.url` field in the transaction response to automatically open a checkout for the transaction using [your default payment link](https://developer.paddle.com/build/transactions/default-payment-link.md).
- Extract the `id` and pass to Paddle.js to open a checkout. To learn more, see [Pass a transaction to a checkout](https://developer.paddle.com/build/transactions/pass-transaction-checkout.md)

#### Show on-page information

[Overlay checkout](https://developer.paddle.com/concepts/sell/overlay-checkout.md) includes items, totals, and a message to let customers know what the checkout is for.

[Inline checkout](https://developer.paddle.com/concepts/sell/branded-integrated-inline-checkout.md) doesn't include items or totals. It's designed to capture payment information, letting you embed information about the transaction on your page.

You might like to build your own logic to display information about this transaction. Pass an `eventCallback` to [`Paddle.Initialize()`](https://developer.paddle.com/paddlejs/methods/paddle-initialize.md) to listen for the [`checkout.loaded`](https://developer.paddle.com/paddlejs/general/checkout-loaded.md) event, then update on-page elements based on the event emitted.

- **For past due subscriptions, `data.status` is `past_due`.**  
  You should include items and totals, and may like to show a message to let customers know this checkout is to pay for a past due payment and update the payment method on file.
- **For active subscriptions, `data.totals.subtotal` is `0`.**  
  You should show a message to let customers know this checkout is to update the payment method on file.

## Events

For a full list of events that occur when a payment method is updated, see [Payment method update](https://developer.paddle.com/build/lifecycle/payment-details-update.md)