# GET /subscriptions/{subscription_id}/update-payment-method-transaction

**Get a transaction to update payment method**

Returns a transaction that you can pass to a checkout to let customers update their payment details. Only for subscriptions where `collection_mode` is `automatic`.

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

* Where a subscription is `past_due`, it returns the most recent `past_due` transaction.
* Where a subscription is `active`, it creates a new zero amount transaction for the items on a subscription.

You can use the returned `checkout.url`, or pass the returned transaction ID to Paddle.js to open a checkout to present customers with a way of updating their payment details.

The `customer`, `address`, `business`, `discount`, `adjustments` and `adjustments_totals` properties are only returned in the response if the API key has read permissions for those related entities.

**Required permissions:** `transaction.write`

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `subscription_id` | string | required | Paddle ID of the subscription entity to work with. |

## Response (200)

- `data`: object (required)
  - `id`: string (required) — Unique Paddle ID for this transaction entity, prefixed with `txn_`. (pattern: `^txn_[a-z\d]{26}$`)
  - `status`: string (required) — Status of this transaction. You may set a transaction to `billed` or `canceled`, other statuses are set automatically by Paddle. Automatically-collected transactions may return `completed` if payment is captured successfully, or `past_due` if payment failed.
  - `customer_id` (required) — Paddle ID of the customer that this transaction is for, prefixed with `ctm_`.
  - `address_id` (required) — Paddle ID of the address that this transaction is for, prefixed with `add_`.
  - `business_id` (required) — Paddle ID of the business that this transaction is for, prefixed with `biz_`.
  - `custom_data` (required) — Your own structured key-value data.
  - `currency_code`: string (required) — Supported three-letter ISO 4217 currency code. Must be `USD`, `EUR`, or `GBP` if `collection_mode` is `manual`.
  - `origin` (required) — Describes how this transaction was created.
  - `subscription_id` (required) — Paddle ID of the subscription that this transaction is for, prefixed with `sub_`.
  - `invoice_id` (required) — Paddle ID of the invoice that this transaction is related to, prefixed with `inv_`. Used for compatibility with the Paddle Invoice API, which is now deprecated. This field is scheduled to be removed in the next version of the Paddle API. (pattern: `^inv_[a-z\d]{26}$`)
  - `invoice_number` (required) — Invoice number for this transaction. Automatically generated by Paddle when you mark a transaction as `billed` where `collection_mode` is `manual`.
  - `collection_mode`: string (required) — How payment is collected for this transaction. `automatic` for checkout, `manual` for invoices.
  - `discount_id` (required) — Paddle ID of the discount applied to this transaction, prefixed with `dsc_`.
  - `billing_details` (required) — Details for invoicing. Required if `collection_mode` is `manual`.
  - `billing_period` (required) — Time period that this transaction is for. Set automatically by Paddle for subscription renewals to describe the period that charges are for.
  - `items`: array (required) — List of items on this transaction. For calculated totals, use `details.line_items`. (Items: 1–100)
  - `details`: object (required) — Calculated totals for a transaction, including proration, discounts, tax, and currency conversion. Considered the source of truth for totals on a transaction.
    - `tax_rates_used`: array (required) — List of tax rates applied for this transaction.
    - `totals`: object (required) — Breakdown of the total for a transaction. These numbers can be negative when dealing with subscription updates that result in credit.
      - `subtotal`: string (required) — Subtotal before discount, tax, and deductions. If an item, unit price multiplied by quantity.
      - `discount`: string (required) — Total discount as a result of any discounts applied.

Except for percentage discounts, Paddle applies tax to discounts based on the line item `price.tax_mode`. If `price.tax_mode` for a line item is `internal`, Paddle removes tax from the discount applied.
      - `tax`: string (required) — Total tax on the subtotal.
      - `total`: string (required) — Total after discount and tax.
      - `credit`: string (required) — Total credit applied to this transaction. This includes credits applied using a customer's credit balance and adjustments to a `billed` transaction.
      - `credit_to_balance`: string (required) — Additional credit generated from negative `details.line_items`. This credit is added to the customer balance.
      - `balance`: string (required) — Total due on a transaction after credits and any payments.
      - `grand_total`: string (required) — Total due on a transaction after credits but before any payments.
      - `grand_total_tax`: string (required) — Net tax amount included in `grand_total`. Equals the full `tax` amount unless credits are applied, in which case this value is proportionally reduced.
      - `fee` (required) — Total fee taken by Paddle for this transaction. `null` until the transaction is `completed` and the fee is processed.
      - `earnings` (required) — Total earnings for this transaction. This is the total minus the Paddle fee. `null` until the transaction is `completed` and the fee is processed.
      - `currency_code`: string (required) — Three-letter ISO 4217 currency code of the currency used for this transaction.
    - `adjusted_totals`: object (required) — Breakdown of the totals for a transaction after adjustments.
      - `subtotal`: string (required) — Subtotal before discount, tax, and deductions. If an item, unit price multiplied by quantity.
      - `tax`: string (required) — Total tax on the subtotal.
      - `total`: string (required) — Total after tax.
      - `grand_total`: string (required) — Total due after credits but before any payments.
      - `grand_total_tax`: string (required) — Net tax amount included in `grand_total`. Equals the full `tax` amount unless credits are applied, in which case this value is proportionally reduced.
      - `fee` (required) — Total fee taken by Paddle for this transaction. `null` until the transaction is `completed` and the fee is processed.
      - `retained_fee`: string (required) — Total Paddle fees retained for this adjustment.
      - `earnings` (required) — Total earnings for this transaction. This is the total minus the Paddle fee.
`null` until the transaction is `completed` and the fee is processed.
      - `currency_code`: string (required) — Three-letter ISO 4217 currency code of the currency used for this transaction.
    - `payout_totals` (required) — Breakdown of the payout total for a transaction. `null` until the transaction is `completed`. Returned in your payout currency.
    - `adjusted_payout_totals` (required) — Breakdown of the payout total for a transaction after adjustments. `null` until the transaction is `completed`.
    - `line_items`: array (required) — Information about line items for this transaction. Different from transaction `items` as they include totals calculated by Paddle. Considered the source of truth for line item totals.
  - `payments`: array (required) — List of payment attempts for this transaction, including successful payments. Sorted by `created_at` in descending order, so most recent attempts are returned first.
  - `checkout` (required)
  - `created_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
  - `updated_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
  - `billed_at` (required) — RFC 3339 datetime string of when this transaction was marked as `billed`. `null` for transactions that aren't `billed` or `completed`. Set automatically by Paddle.
  - `revised_at` (required) — RFC 3339 datetime string of when a transaction was revised. Revisions describe an update to customer information for a billed or completed transaction. `null` if not revised. Set automatically by Paddle.
  - `customer`: object — Related customer for this transaction. Only returned if the API key has a Customers (Read) permission.
    - `id`: string (required) — Unique Paddle ID for this customer entity, prefixed with `ctm_`. (pattern: `^ctm_[a-z\d]{26}$`)
    - `name` (required) — Full name of this customer. Required when creating transactions where `collection_mode` is `manual` (invoices).
    - `email`: string (email) (required) — Email address for this customer. (Length: 1–320)
    - `marketing_consent`: boolean (required) — Whether this customer opted into marketing from you. `false` unless customers check the marketing consent box
when using Paddle Checkout. Set automatically by Paddle.
    - `status`: string (required) — Whether this entity can be used in Paddle.
    - `custom_data` (required) — Your own structured key-value data.
    - `locale`: string (required) — Valid IETF BCP 47 short form locale tag. If omitted, defaults to `en`.
    - `created_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
    - `updated_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
    - `import_meta` (required) — Import information for this entity. `null` if this entity is not imported.
  - `address`: object — Related address for this transaction. Only returned if the API key has an Addresses (Read) permission.
    - `id`: string (required) — Unique Paddle ID for this address entity, prefixed with `add_`. (pattern: `^add_[a-z\d]{26}$`)
    - `customer_id`: string (required) — Paddle ID for the customer related to this address, prefixed with `cus_`. (pattern: `^ctm_[a-z\d]{26}$`)
    - `description` (required)
    - `first_line` (required)
    - `second_line` (required)
    - `city` (required)
    - `postal_code` (required)
    - `region` (required)
    - `country_code` (required) — Supported two-letter ISO 3166-1 alpha-2 country code for this address.
    - `custom_data` (required) — Your own structured key-value data.
    - `status`: string (required) — Whether this entity can be used in Paddle.
    - `created_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
    - `updated_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
    - `import_meta` (required)
  - `business`: object — Related business for this transaction. Only returned if a business exists for this transaction and the API key has a Businesses (Read) permission.
    - `id`: string (required) — Unique Paddle ID for this business entity, prefixed with `biz_`. (pattern: `^biz_[a-z\d]{26}$`)
    - `customer_id`: string (required) — Paddle ID for the customer related to this business, prefixed with `cus_`. (pattern: `^ctm_[a-z\d]{26}$`)
    - `name`: string (required) — Name of this business. (Length: 1–1024)
    - `company_number` (required) — Company number for this business. (Max length: 1024)
    - `tax_identifier` (required) — Tax or VAT Number for this business. (Max length: 1024)
    - `status`: string (required) — Whether this entity can be used in Paddle.
    - `contacts`: array (required) — List of contacts related to this business, typically used for sending invoices. (Items: max 100, unique)
    - `created_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
    - `updated_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
    - `custom_data` (required) — Your own structured key-value data.
    - `import_meta` (required) — Import information for this entity. `null` if this entity is not imported.
  - `discount`: object — Related discount for this transaction. Only returned if a discount exists for this transaction and the API key has a Discounts (Read) permission.
    - `id`: string (required) — Unique Paddle ID for this discount, prefixed with `dsc_`. (pattern: `^dsc_[a-z\d]{26}$`)
    - `status`: string (required) — Whether this entity can be used in Paddle.
    - `description`: string (required) — Short description for this discount for your reference. Not shown to customers. (Length: 1–500)
    - `enabled_for_checkout`: boolean (required) — Whether this discount can be redeemed by customers at checkout (`true`) or not (`false`).
    - `code` (required) — Unique code that customers can use to redeem this discount at checkout. Not case-sensitive.
    - `type`: string (required) — Type of discount. Determines how this discount impacts the checkout or transaction total.
    - `mode`: string (required) — Discount mode. Standard discounts are considered part of your catalog and are shown in the Paddle dashboard.
    - `amount`: string (required) — Amount to discount by. For `percentage` discounts, must be an amount between `0.01` and `100`. For `flat` and `flat_per_seat` discounts, amount in the lowest denomination for a currency.
    - `currency_code` (required) — Supported three-letter ISO 4217 currency code. Required where discount type is `flat` or `flat_per_seat`.
    - `recur`: boolean (required) — Whether this discount applies for multiple subscription billing periods (`true`) or not (`false`).
    - `maximum_recurring_intervals` (required) — Number of subscription billing periods that this discount recurs for. Requires `recur`. `null` if this discount recurs forever.

Subscription renewals, midcycle changes, and one-time charges billed to a subscription aren't considered a redemption. `times_used` is not incremented in these cases. (Min: 1)
    - `usage_limit` (required) — Maximum number of times this discount can be redeemed. This is an overall limit for this discount, rather than a per-customer limit. `null` if this discount can be redeemed an unlimited amount of times.

Paddle counts a usage as a redemption on a checkout, transaction, or the initial application against a subscription. Transactions created for subscription renewals, midcycle changes, and one-time charges aren't considered a redemption. (Min: 1)
    - `restrict_to` (required) — Product or price IDs that this discount is for. When including a product ID, all prices for that product can be discounted. `null` if this discount applies to all products and prices. (Items: unique)
    - `expires_at` (required) — RFC 3339 datetime string of when this discount expires. Discount can no longer be redeemed after this date has elapsed. `null` if this discount can be redeemed forever.

Expired discounts can't be redeemed against transactions or checkouts, but can be applied when updating subscriptions.
    - `custom_data` (required)
    - `times_used`: integer (required) — How many times this discount has been redeemed. Automatically incremented by Paddle.

Paddle counts a usage as a redemption on a checkout, transaction, or subscription. Transactions created for subscription renewals, midcycle changes, and one-time charges aren't considered a redemption.
    - `discount_group_id` (required) — Paddle ID for the discount group related to this discount, prefixed with `dsg_`. `null` if not in a discount group.
    - `created_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
    - `updated_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
    - `import_meta` (required) — Import information for this entity. `null` if this entity is not imported.
  - `adjustments`: array (required) — Related adjustments for this transaction. Only returned if adjustments exist for this transaction and the API key has an Adjustments (Read) permission.
  - `adjustments_totals`: object — Object containing totals for all adjustments on this transaction. Only returned if the API key has an Adjustments (Read) permission.
    - `subtotal`: string (required) — Total before tax.
    - `tax`: string (required) — Total tax on the subtotal.
    - `total`: string (required) — Total after tax.
    - `fee`: string (required) — Total fee taken by Paddle.
    - `retained_fee`: string (required) — Total gateway fee retained by Paddle.
    - `earnings`: string (required) — Total earnings. This is the subtotal minus the Paddle fee.
For tax adjustments, this value is negative, which means a positive effect in the transaction earnings.
This is because the fee is originally calculated from the transaction total, so if a tax adjustment is made,
then the fee portion of it is returned.
As a result, the earnings from all the adjustments performed could be either negative, positive or zero.
    - `breakdown`: object (required) — Breakdown of the total adjustments by adjustment action.
      - `credit`: string (required) — Total amount of credit adjustments.
      - `refund`: string (required) — Total amount of refund adjustments.
      - `chargeback`: string (required) — Total amount of chargeback adjustments.
    - `currency_code`: string (required) — Three-letter ISO 4217 currency code used for adjustments for this transaction.
  - `available_payment_methods`: array (required) — List of payment methods available for this transaction.
- `meta`: object (required) — Information about this response.
  - `request_id`: string (required) — Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.

### Response example

```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"
  }
}
```