Paddle Billing
Search

Work with custom data

Include your own custom information when working with checkouts and some entities in the Paddle API. 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, 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.

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.

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.

POSThttps://api.paddle.com/transactions

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.

Response

If successful, Paddle responds with the complete transaction entity including custom_data.

Get custom data

Once added to a transaction, you can see custom data:

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.

POSThttps://api.paddle.com/transactions/{transaction_id}
transaction_idstring

Paddle ID of the transaction entity to work with.

Response

If successful, Paddle responds with the complete transaction entity including custom_data.

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.

Request

Remove custom data

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

Related pages