Work with custom data
Include your own custom information when working with checkouts, transactions, or subscriptions. Great for storing metadata or other useful information when working with third-party solutions.
Custom data lets you add your own key-value data to subscriptions and transactions created using Paddle Checkout or the API.
You can use custom data for things like:
- Capturing UTM source or marketing campaign information
- Storing metadata or other useful information for third-party integrations
How it works
You can add custom data to subscriptions and transactions using the API or Paddle.js. Both entities have a custom_data
object against them, which accepts valid key-value JSON data.
You can see custom data in the Dashboard, but you can't create it there. It's primarily designed for storing metadata or information that might need to be shared across systems.
When working with a checkout, you can pass custom data in a similar way to prefilling properties. Any custom data is held against the related transaction.
Paddle automatically creates a subscription for transactions with recurring prices on them. Where a transaction has custom data against it, that data is copied to the created subscription for your reference. Future transactions created from that subscription don't include this custom data.
We recommend against nesting custom data. Though there's no limitations on having objects inside the
custom_data
object, you might find this information isn't displayed in the Dashboard correctly.
Before you begin
To pass custom data to a checkout, you'll need to use Paddle.js to build a checkout:
You'll need to create products and prices to add them to a checkout or transaction.
If you're working with the API, you'll need a customer and a related address. Checkout automatically creates customers and addresses for you as part of the journey.
Pass custom data to checkout
Pass custom data to a checkout using an HTML data attribute or JavaScript property.
Add a data-custom-data
HTML attribute to your checkout trigger to add custom data to the created transaction.
12345678910111213141516171819201<a
2 href='#'
3 class='paddle_button'
4 data-theme='light'
5 data-custom-data='{
6 'utm_medium': 'social',
7 'utm_source': 'linkedin',
8 'utm_content': 'launch-video',
9 'integration_id': 'AA-123'
10 }'
11 data-customer-address-country-code='US'
12 data-customer-email='weloveyourproduct@paddle.com'
13 data-items='[
14 {
15 "priceId": "pri_01gs59hve0hrz6nyybj56z04eq",
16 "quantity": 1
17 },
18 {
19 "priceId": "pri_01gs59p7rcxmzab2dm3gfqq00a",
20 "quantity": 1
For a full list of HTML data attributes, see: HTML data attributes
Add custom data to a transaction
You can add custom data when creating or updating a transaction. You might do this when setting up a transaction to pass to a checkout, or when working with an invoice (a manually-collected transaction).
To create, send a POST request to the /transactions
endpoint, including a JSON object of custom_data
.
To update, send a PATCH request to the /transactions/{transaction_id}
endpoint, including a JSON object of custom_data
.
Paddle ID of the transaction entity to work with.
Request
This example adds UTM information to new automatically-collected transaction.
12345678910111213141516171{
2 "items": [
3 {
4 "quantity": 10,
5 "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke"
6 }
7 ],
8 "customer_id": "ctm_01gywfmzk8038netxxbhk80vwe",
9 "address_id": "add_01gywfmzn2dwxry2rhry1b5gj4",
10 "custom_data": {
11 "utm_source": "crm",
12 "utm_medium": "email",
13 "utm_content": "closed-deal",
14 "integration_id": "AA-123"
15 },
16 "collection_mode": "automatic"
17}
Response
If successful, Paddle responds with the complete transaction entity including custom_data
.
12345678910111213141516171819201{
2 "data": {
3 "id": "txn_01gyyw3j6khyc2fpy3ttapzf9v",
4 "status": "ready",
5 "customer_id": "ctm_01gywfmzk8038netxxbhk80vwe",
6 "address_id": "add_01gywfmzn2dwxry2rhry1b5gj4",
7 "business_id": null,
8 "custom_data": {
9 "utm_source": "crm",
10 "utm_medium": "email",
11 "utm_content": "closed-deal",
12 "integration_id": "AA-123"
13 },
14 "origin": "api",
15 "collection_mode": "automatic",
16 "subscription_id": null,
17 "invoice_id": null,
18 "invoice_number": null,
19 "billing_details": null,
20 "billing_period": null,
Get custom data
Once added to a transaction, you can see custom data:
- In the Paddle dashboard against a transaction
- Using the API by getting a transaction entity
- In webhooks for transaction events
If your transaction creates a new subscription, the custom data is copied to the new subscription. You can see it against the subscription in the Dashboard or when working with a subscription entity using the API.
Send a GET request to the /transactions/{transaction_id}
endpoint.
Paddle ID of the transaction entity to work with.
Response
If successful, Paddle responds with the complete transaction entity including custom_data
.
12345678910111213141516171819201{
2 "data": {
3 "id": "txn_01gyyw3j6khyc2fpy3ttapzf9v",
4 "status": "ready",
5 "customer_id": "ctm_01gywfmzk8038netxxbhk80vwe",
6 "address_id": "add_01gywfmzn2dwxry2rhry1b5gj4",
7 "business_id": null,
8 "custom_data": {
9 "utm_source": "crm",
10 "utm_medium": "email",
11 "utm_content": "closed-deal",
12 "integration_id": "AA-123"
13 },
14 "origin": "api",
15 "collection_mode": "automatic",
16 "subscription_id": null,
17 "invoice_id": null,
18 "invoice_number": null,
19 "billing_details": null,
20 "billing_period": null,
Update or remove custom data
You can update or remove custom data against a transaction or subscription using the API. You can't create or update custom data using the Dashboard.
Transactions are financial records. You can't edit them if they're billed, canceled, or completed.
To update, send a PATCH request to the /transactions/{transaction_id}
endpoint, including a JSON object of custom_data
.
Paddle ID of the transaction entity to work with.
Request
123451{
2 "custom_data": {
3 "integration_id": "BB-456"
4 }
5}
Remove custom data
To remove custom data, set custom_data
to null
when updating.
1231{
2 "custom_data": null
3}