For AI agents and LLMs: a structured documentation index is available at /llms.txt. Every page has a Markdown sibling — append .md to any URL.

Skip to content
Docs

Update payment details

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

AI summary

Build a workflow to let customers update their payment method for a subscription by creating an update payment method transaction and passing it to Paddle.js to open a checkout.

  • • Create an update payment method transaction via the API, then pass its transaction_id to Paddle.Checkout.open() to collect the new payment details.
  • • Payment method updates are available for automatically-collected subscriptions that are active or past_due — manually-collected (invoice) subscriptions don't use saved payment methods.
  • • The default payment link must be set in your Paddle account and approved before customers can update payment details — it's included in Paddle's automated dunning emails too.

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.

Screenshot of an overlay checkout for an update payment method transaction.

How it works

When payment fails for an automatically-collected subscription, 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.

You can build a workflow to let a customer update their payment details using Paddle Checkout, which handles securely capturing card details or payment using another payment method.

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 to get a transaction that you can pass to Paddle.js to open a Paddle Checkout for it.

The returned transaction depends on the status of the related subscription:

Past due subscription

Overlay checkout for an update payment method transaction. The subscription is past due, and the customer is charged for the past due payment.

When the subscription status is past_due, the last past_due transaction is returned.

Overlay checkout

Displays the items and totals for the overdue transaction, so that customers know they'll be charged when they update their details.

Inline checkout

Includes an "Update payment method" button letting customers update payment details and pay the overdue amount.

Active subscription

Overlay checkout for an update payment method transaction. The subscription is active and the customer is charged for $0.

When the subscription status is active, Paddle creates a zero-value transaction for the subscription's items.

Overlay checkout

Displays the subscription's items and shows a message indicating the customer is updating their payment details, with no charge due.

Inline checkout

Includes an "Update payment method" button letting customers update their details without making a payment.

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

To update payment details for a subscription, you'll need to get the subscription ID 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. This is typically your default payment link.

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

  • Add a default payment link to your checkout under Paddle > Checkout > Checkout settings > Default payment link.
  • Get your default payment link domain approved if you're working with the live environment.

Use the portal Recommended

The quickest way to let customers update payment details is to link them to the customer portal. 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.

POST /customers/{customer_id}/portal-sessions
Request
{
  "subscription_ids": [
    "sub_01jcgfqad406rsfjcgq44g9djq",
    "sub_01jcdafvpe5hm4vczfefsbwhvp"
  ]
}
Response (201 Created)
{
  "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"
  }
}

For more information, see Use customer portal links in your app.

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.

GET /subscriptions/{subscription_id}

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 and Paddle.js. Use this approach when you want full control over the look and feel of the update flow, like presenting an inline checkout 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

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:

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.

GET /subscriptions/{subscription_id}/update-payment-method-transaction
Response (200 OK)
{
  "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"
  }
}

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.

GET /subscriptions/{subscription_id}/update-payment-method-transaction
Response (200 OK)
{
  "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"
  }
}

Pass a transaction to a checkout

Once you have a payment method update transaction, pass it to Paddle.js to open a checkout for it. To do this, you can either:

Show on-page information

Overlay checkout includes items, totals, and a message to let customers know what the checkout is for.

Inline checkout 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() to listen for the checkout.loaded 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

Was this page helpful?