PApaddlehq
Transactions

Update a transaction

Changed on

Updates a transaction using its ID.

You can update transactions that are draft or ready. billed and completed transactions are considered records for tax and legal purposes, so they can't be changed. You can either:

  • Create an adjustment to record a refund or credit for a transaction.
  • Cancel a billed transaction by sending a PATCH request to set status to canceled.

You can cancel transactions that are draft, ready, billed, or past_due. When canceling, only include status in your request. You can't use the API to cancel transactions that Paddle created for a subscription, where origin starts with subscription_, or automatically-collected transactions that are past_due. Cancel transactions created for a subscription using the Paddle dashboard.

The transaction status may only be set to billed or canceled. Other statuses are set automatically by Paddle. Set a manually-collected transaction to billed to mark it as finalized. This is essentially issuing an invoice. At this point, it becomes a legal record so you can't make changes to it, only cancel it. Paddle automatically assigns an invoice number, creates a related subscription, and sends it to your customer.

When making changes to items on a transaction, send the complete list of items that you'd like to be on a transaction — including existing items. For each item, send an object containing price_id and quantity. Paddle responds with the full price object for each item. See: Work with lists

If successful, your response includes a copy of the updated transaction entity.

patch/transactions/{transaction_id}

Request

  • Base URL
    https://sandbox-api.paddle.com
  • Auth
    HTTP bearer

Path parameters

transaction_idstring required

Paddle ID of the transaction entity to work with.

Query parameters

includeTransactionIncludeQuery[]

Include related entities in the response. Use a comma-separated list to specify multiple entities.

Request body

idstring

Unique Paddle ID for this transaction entity, prefixed with txn_.

status'draft' | 'ready' | 'billed' | 'paid' | 'completed' | 'canceled' | 'past_due'

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_idstring

Unique Paddle ID for this customer entity, prefixed with ctm_.

address_idstring

Unique Paddle ID for this address entity, prefixed with add_.

business_idstring

Unique Paddle ID for this business entity, prefixed with biz_.

custom_dataCustomData

Your own structured key-value data.

currency_code'USD' | 'EUR' | 'GBP' | 'JPY' | 'AUD' | 'CAD' | 'CHF' | 'HKD' | 'SGD' | 'SEK' | 'ARS' | 'BRL' | 'CLP' | 'CNY' | 'COP' | 'CZK' | 'DKK' | 'HUF' | 'ILS' | 'INR' | 'KRW' | 'MXN' | 'NOK' | 'NZD' | 'PEN' | 'PLN' | 'RUB' | 'THB' | 'TRY' | 'TWD' | 'UAH' | 'VND' | 'ZAR'

Supported three-letter ISO 4217 currency code.

origin'api' | 'subscription_charge' | 'subscription_payment_method_change' | 'subscription_recurring' | 'subscription_update' | 'web'
subscription_idstring nullable

Unique Paddle ID for this subscription entity, prefixed with sub_.

invoice_idstring nullable

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.

invoice_numberstring nullable

Invoice number for this transaction. Automatically generated by Paddle when you mark a transaction as billed where collection_mode is manual.

collection_mode'automatic' | 'manual'

How payment is collected. automatic for checkout, manual for invoices.

discount_idstring

Unique Paddle ID for this discount, prefixed with dsc_.

created_atstring date-time

RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.

updated_atstring date-time

RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.

billed_atstring date-time

RFC 3339 datetime string.

Example request

{
  "id": "txn_01h04vsbhqc62t8hmd4z3b578c",
  "customer_id": "ctm_01grnn4zta5a1mf02jjze7y2ys",
  "address_id": "add_01gm302t81w94gyjpjpqypkzkf",
  "business_id": "biz_01grrebrzaee2qj2fqqhmcyzaj",
  "custom_data": {
    "customer_reference_id": "abcd1234"
  },
  "subscription_id": "sub_01h04vsc0qhwtsbsxh3422wjs4",
  "invoice_id": "inv_01ghbk4xjn4qdsmstcwzgcgg35",
  "invoice_number": "123-45678",
  "discount_id": "dsc_01gv5kpg05xp104ek2fmgjwttf",
  "discount": {
    "custom_data": {
      "customer_reference_id": "abcd1234"
    }
  },
  "billing_period": {
    "starts_at": "2024-10-12T07:20:50.52Z",
    "ends_at": "2024-10-12T07:20:50.52Z"
  },
  "items": [
    {
      "proration": {
        "billing_period": {
          "starts_at": "2024-10-12T07:20:50.52Z",
          "ends_at": "2024-10-12T07:20:50.52Z"
        }
      },
      "price_id": "pri_01gsz8z1q1n00f12qt82y31smh"
    }
  ],
  "details": {
    "tax_rates_used": [
      {
        "tax_rate": "0.2",
        "totals": {
          "subtotal": "15000",
          "discount": "0",
          "tax": "1500",
          "total": "16500"
        }
      }
    ],
    "totals": {
      "subtotal": "15000",
      "discount": "0",
      "tax": "1500",
      "total": "16500",
      "credit": "0",
      "credit_to_balance": "0",
      "balance": "16500",
      "grand_total": "16500",
      "grand_total_tax": "83",
      "fee": "825",
      "earnings": "15675"
    },
    "adjusted_totals": {
      "subtotal": "15000",
      "tax": "1500",
      "total": "16500",
      "grand_total": "16500",
      "grand_total_tax": "83",
      "fee": "825",
      "retained_fee": "300",
      "earnings": "15675"
    },
    "payout_totals": {
      "subtotal": "15000",
      "discount": "0",
      "tax": "1500",
      "total": "16500",
      "credit": "0",
      "credit_to_balance": "0",
      "balance": "16500",
      "grand_total": "16500",
      "grand_total_tax": "83",
      "fee": "825",
      "earnings": "15675",
      "exchange_rate": "1.0513135",
      "fee_rate": "0.05"
    },
    "adjusted_payout_totals": {
      "subtotal": "15000",
      "tax": "1500",
      "total": "16500",
      "fee": "825",
      "retained_fee": "300",
      "chargeback_fee": {
        "amount": "1680",
        "original": {
          "amount": "1500"
        }
      },
      "earnings": "15675",
      "exchange_rate": "1.0513135"
    },
    "line_items": [
      {
        "price_id": "pri_01gsz8z1q1n00f12qt82y31smh",
        "proration": {
          "billing_period": {
            "starts_at": "2024-10-12T07:20:50.52Z",
            "ends_at": "2024-10-12T07:20:50.52Z"
          }
        },
        "tax_rate": "0.2",
        "unit_totals": {
          "subtotal": "15000",
          "discount": "0",
          "tax": "1500",
          "total": "16500"
        },
        "totals": {
          "subtotal": "15000",
          "discount": "0",
          "tax": "1500",
          "total": "16500"
        },
        "product": {
          "id": "pro_01gsz97mq9pa4fkyy0wqenepkz",
          "custom_data": {
            "customer_reference_id": "abcd1234"
          },
          "import_meta": {
            "external_id": "9b95b0b8-e10f-441a-862e-1936a6d818ab",
            "imported_from": "paddle_classic"
          },
          "created_at": "2024-10-12T07:20:50.52Z",
          "updated_at": "2024-10-13T07:20:50.52Z"
        },
        "id": "txnitm_01gm302t81w94gyjpjpqypkzkf"
      }
    ]
  },
  "payments": [
    {
      "payment_attempt_id": "497f776b-851d-4ebf-89ab-8ba0f75d2d6a",
      "stored_payment_method_id": "7636e781-3969-49f4-9c77-8226232e28a6",
      "payment_method_id": "paymtd_01hkm9xwqpbbpr1ksmvg3sx3v1",
      "amount": "1050",
      "method_details": {
        "south_korea_local_card": {
          "last4": "4242"
        },
        "card": {
          "last4": "4242",
          "expiry_month": 12,
          "expiry_year": 2028
        },
        "paypal": {
          "email": "john.doe@example.com"
        }
      },
      "created_at": "2024-10-12T07:20:50.52Z",
      "captured_at": "2024-10-12T07:20:50.52Z"
    }
  ],
  "created_at": "2024-10-12T07:20:50.52Z",
  "updated_at": "2024-10-13T07:20:50.52Z",
  "billed_at": "2024-10-12T07:20:50.52Z"
}

Response

The request has succeeded.

Changes

  • v1bbc0c72039c8Revision changes
    • breaking

      removed from the request property oneOf list

    • info

      removed from the ///// response property oneOf list for the response status

  • v14f35a8c6ea4dRevision changes
    • breaking

      removed from the ///// request property anyOf list

    • breaking

      removed from the ///// request property anyOf list

    • breaking

      added to the /////// response property oneOf list for the response status

    • breaking

      added to the ////////// response property oneOf list for the response status

    • breaking

      added to the //////// response property oneOf list for the response status

    • warning

      added the new blocked_by_policy enum value to the //// response property for the response status

    • info

      added to the ///// request property anyOf list

    • info

      added to the ///// request property anyOf list

    • info

      request property ////// deprecated

    • info

      request property /////// deprecated

    • info

      request property //////// deprecated

    • info

      added the new blocked_by_policy enum value to the request property ///

    • info

      added to the //////// request property oneOf list

    • info

      added to the //////// request property oneOf list

    • info

      response property data/payments/items/method_details/underlying_details/anyOf[subschema #1: PaymentMethodUnderlyingDetails]/korea_local/anyOf[subschema #1: Korean market underlying details]/ deprecated

    • info

      response property data/payments/items/method_details/underlying_details/anyOf[subschema #1: PaymentMethodUnderlyingDetails]/korea_local/anyOf[subschema #1: Korean market underlying details]/type deprecated

    • info

      response property data/payments/items/method_details/underlying_details/anyOf[subschema #1: PaymentMethodUnderlyingDetails]/korea_local/anyOf[subschema #1: Korean market underlying details]/type/allOf[subschema #1: Korean market underlying payment method type]/ deprecated