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 transactions and subscriptions using the API or Paddle.js. Both entities have a custom_data object against them, which accepts valid key-value JSON data.

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 shares custom data between transactions and subscriptions:

• 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.
• Where a subscription has custom data against it, that data is copied to any transactions created from it for things like renewals, upgrades and downgrades, and one-time charges.

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 Paddle 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 a transaction creates a new subscription, the custom data is copied to the new subscription. You can see it against the subscription in the Paddle 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.

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