Revise customer details on a billed or completed transaction

Sometimes customers might want to update their details after they've completed a checkout, or after you've issued an invoice. For example, they might want to add a tax number or fill out their address.

You can revise a transaction to update some customer, address, or business details for it. The existing transaction entity remains on your system unchanged for recordkeeping purposes.

How it works

Paddle automatically sends customers an email receipt when a transaction is completed, like when a customer completes checkout or a subscription renews. Email receipts include a PDF invoice that customers can retain for recordkeeping.

It's common for customers to want to update their details on the included PDF. For example, Paddle Checkout only requires that customers enter their country (and in some cases their ZIP code) to keep the checkout journey short. In this case, customers might want to populate the other fields that are part of their address, like their street address and state.

As billed and completed transactions are financial records, they can't be deleted or changed directly. Instead, you can revise customer, address, and business information for a transaction. The related customer information for that transaction is updated, but the existing transaction entity remains on your system unchanged for recordkeeping purposes.

Related entities

Completed and billed transactions must have a related customer and address entity, and may have a related business entity. They're linked using the customer_id, address_id, and business_id fields. You can use the include query parameter to get the related customer, address, and business entities for a transaction.

When a customer, address, or business is set against a transaction, Paddle creates a relationship between the transaction and the related entity at that moment. This means that if you update a customer, address, or business after it's been set against a transaction, those changes aren't reflected when you use the include query parameter to get the related entities.

You can revise a transaction to update the customer, address, and business entities for a transaction. When you revise a transaction, you're only updating the customer, address, and business information for that particular transaction. The related customer, address, and business entities aren't updated.

Adjustments

Adjustments are another way you can describe updates to a transaction after it's been billed or completed. However, they're used to describe financial changes, like refunding or crediting some or all the items on a transaction.

When you revise customer information for a transaction, Paddle may create an adjustment if there are financial changes. For example, if you add a valid tax or VAT number, Paddle automatically creates an adjustment to refund any tax where applicable.

You can't revise customer information for a transaction that has an adjustment.

Revise a transaction

Revise a transaction using the API in three steps:

1. Build request

   Build a request that includes the customer information that you want to update.

2. Revise transaction

   Send the request to revise the transaction. Paddle revises the related entities.

3. Get transaction including revised information — optional

   Get the related customer, address, and business for a transaction using the include parameter to see the revised information.

Build request

Request

1
2
3
4
5
6
7
8
9
10
11
1{
2  "customer": {
3    "name": "Sam Miller"
4  },
5  "business": {
6    "tax_identifier": "AB0123456789"
7  },
8  "address": {
9    "first_line": "3811 Ditmars Blvd"
10  }
11}

Revise transaction

Send a POST request to the /transactions/{transaction_id}/revise endpoint with the request you built.

Response

If successful, Paddle responds with a copy of the transaction entity. As the information revised is customer, address, and business details, it's not included in the response.

revised_at is set to the date and time you revised this transaction.

15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
15    "billing_period": {
16      "starts_at": "2024-04-12T10:18:47.635628Z",
17      "ends_at": "2024-05-12T10:18:47.635628Z"
18    },
19    "currency_code": "USD",
20    "discount_id": null,
21    "created_at": "2024-04-12T10:12:33.2014Z",
22    "updated_at": "2024-07-26T08:46:00.746349Z",
23    "billed_at": "2024-04-12T10:18:48.294633Z",
24    "revised_at": "2024-07-26T08:46:00.746349Z",
25    "items": [
26      {
27        "price": {
28          "id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
29          "description": "Monthly",
30          "type": "standard",
31          "name": "Monthly (per seat)",
32          "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
33          "billing_cycle": {
34            "interval": "month",

Get a transaction including revised information — optional

Paddle automatically sends a copy of the revised invoice to customers, so you don't need to do anything.

You can get a transaction using the include parameter with the customer, address, and business values to see the revised customer information. You might present this to a customer in a billing screen in your frontend.

Response

If successful, Paddle responds with the transaction entity with the revised customer, address, and business included.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "data": {
3    "id": "txn_01j1f27bnwg90nggkgkf52hy34",
4    "status": "completed",
5    "customer_id": "ctm_01j1f28efp7j4p1ae0hqnd144s",
6    "address_id": "add_01j1f28egce2412sjnzp4pxdqg",
7    "business_id": null,
8    "custom_data": null,
9    "origin": "web",
10    "collection_mode": "automatic",
11    "subscription_id": "sub_01j1f28ywb5hn78y2y5tym9y4k",
12    "invoice_id": "inv_01j1f28yyr4abcmbf94g66p9ht",
13    "invoice_number": "325-11071",
14    "billing_details": null,
15    "billing_period": {
16      "starts_at": "2024-06-28T09:19:26.694403Z",
17      "ends_at": "2024-07-28T09:19:26.694403Z"
18    },
19    "currency_code": "USD",
20    "discount_id": null,

Update customer, business, and address entities

When you revise customer information for a transaction, only the customer information for this transaction is updated. The related customer, address, and business entities aren't updated.

Use the dashboard or the Paddle API to update the customer, address, and business entities so that future transactions use the latest data.

Common errors

Events

Related pages