Work with custom data

Custom data lets you add your own key-value data to subscriptions, transactions, and some other entities in the Paddle API 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:

• Build an overlay checkout
• Build an inline 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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1<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

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.

Request

This example adds UTM information to new automatically-collected transaction.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
1{
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.

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_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.

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_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.

1
2
3
4
5
1{
2  "custom_data": {
3    "integration_id": "BB-456"
4  }
5}

Remove custom data

To remove custom data, set custom_data to null when updating.

1
2
3
1{
2  "custom_data": null
3}

Related pages