> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# 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](https://developer.paddle.com/api-reference/transactions/overview.md) and [subscriptions](https://developer.paddle.com/api-reference/transactions/overview.md) using the API or [Paddle.js](https://developer.paddle.com/paddlejs/overview.md). 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](https://developer.paddle.com/build/checkout/prefill-checkout-properties.md). 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.

{% callout type="info" %}
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.
{% /callout %}

## Before you begin

You'll need to [include Paddle.js on your page](https://developer.paddle.com/paddlejs/include-paddlejs.md) and pass a [client-side token](https://developer.paddle.com/paddlejs/client-side-tokens.md).

To open a checkout, you'll need to [create products and prices](https://developer.paddle.com/build/products/create-products-prices.md) and [pass them to a checkout](https://developer.paddle.com/build/checkout/pass-update-checkout-items.md).

## Pass custom data to checkout

Pass custom data to a checkout using an HTML data attribute or JavaScript property.

{% tabs sync="js-html-implementation" %}
{% tab-item title="JavaScript properties" %}

Pass `customData` to the `Paddle.Checkout.open()` method to add custom data to the created transaction.

```javascript title="Checkout open method" highlightLines="15-20"

Paddle.Checkout.open({
  settings: {
    theme: "light",
  },
  items: [
    {
      priceId: 'pri_01gs59hve0hrz6nyybj56z04eq',
      quantity: 1
    },
    {
      priceId: 'pri_01gs59p7rcxmzab2dm3gfqq00a',
      quantity: 1
    }
  ],
  customData: {
    "utm_medium": "social",
    "utm_source": "linkedin",
    "utm_content": "launch-video",
    "integration_id": "AA-123"
  },
  customer: {
    email: "weloveyourproduct@paddle.com",
    address: {
      countryCode: "US",
    }
  }
});

```

For a full list of data you can pass to a checkout, see [`Paddle.Checkout.open()`](https://developer.paddle.com/paddlejs/methods/paddle-checkout-open.md)

{% /tab-item %}
{% tab-item title="HTML data attributes" %}

Add a `data-custom-data` HTML attribute to your checkout launcher to add custom data to the created transaction.

```html title="Checkout launcher element" highlightLines="5-10"

<a 
  href='#' 
  class='paddle_button'
  data-theme='light'
  data-custom-data='{
    "utm_medium": "social",
    "utm_source": "linkedin",
    "utm_content": "launch-video",
    "integration_id": "AA-123"
  }'
  data-customer-address-country-code='US'
  data-customer-email='weloveyourproduct@paddle.com'
  data-items='[
    {
      "priceId": "pri_01gs59hve0hrz6nyybj56z04eq",
      "quantity": 1
    },
    {
      "priceId": "pri_01gs59p7rcxmzab2dm3gfqq00a",
      "quantity": 1
    }
  ]'
>
  Buy Now
</a>

```

For a full list of HTML data attributes, see [HTML data attributes](https://developer.paddle.com/paddlejs/html-data-attributes.md)

{% /tab-item %}
{% /tabs %}

## 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)](https://developer.paddle.com/build/invoices/create-issue-invoices.md).

Send a `POST` request to the `/transactions` endpoint to create a transaction, or `PATCH` to `/transactions/{transaction_id}` to update an existing one.

In your request, include `custom_data` as a JSON object.

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

{% api-example method="POST" path="/transactions" href="/api-reference/transactions/create-transaction" %}

```json
{
  "items": [
    {
      "quantity": 10,
      "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke"
    }
  ],
  "customer_id": "ctm_01gywfmzk8038netxxbhk80vwe",
  "address_id": "add_01gywfmzn2dwxry2rhry1b5gj4",
  "custom_data": {
    "utm_source": "crm",
    "utm_medium": "email",
    "utm_content": "closed-deal",
    "integration_id": "AA-123"
  },
  "collection_mode": "automatic"
}
```

```json
{
  "data": {
    "id": "txn_01gyyw3j6khyc2fpy3ttapzf9v",
    "status": "ready",
    "customer_id": "ctm_01gywfmzk8038netxxbhk80vwe",
    "address_id": "add_01gywfmzn2dwxry2rhry1b5gj4",
    "business_id": null,
    "custom_data": {
      "utm_source": "crm",
      "utm_medium": "email",
      "utm_content": "closed-deal",
      "integration_id": "AA-123"
    },
    "origin": "api",
    "collection_mode": "automatic",
    "subscription_id": null,
    "invoice_id": null,
    "invoice_number": null,
    "billing_details": null,
    "billing_period": null,
    "currency_code": "GBP",
    "discount_id": null,
    "created_at": "2023-04-26T13:30:06.540543605Z",
    "updated_at": "2023-04-26T13:30:06.540543605Z",
    "billed_at": null,
    "items": [
      {
        "price": {
          "id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
          "description": "Monthly (per seat)",
          "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
          "billing_cycle": {
            "interval": "month",
            "frequency": 1
          },
          "trial_period": null,
          "tax_mode": "account_setting",
          "unit_price": {
            "amount": "3000",
            "currency_code": "GBP"
          },
          "unit_price_overrides": [
            {
              "country_codes": ["US"],
              "unit_price": {
                "amount": "4500",
                "currency_code": "USD"
              }
            },
            {
              "country_codes": ["PL"],
              "unit_price": {
                "amount": "8000",
                "currency_code": "PLN"
              }
            },
            {
              "country_codes": ["IN"],
              "unit_price": {
                "amount": "100500",
                "currency_code": "INR"
              }
            },
            {
              "country_codes": ["UA"],
              "unit_price": {
                "amount": "40000",
                "currency_code": "UAH"
              }
            },
            {
              "country_codes": ["NG"],
              "unit_price": {
                "amount": "1400",
                "currency_code": "USD"
              }
            }
          ],
          "quantity": {
            "minimum": 10,
            "maximum": 999
          },
          "status": "active"
        },
        "quantity": 10
      }
    ],
    "details": {
      "tax_rates_used": [
        {
          "tax_rate": "0.2",
          "totals": {
            "subtotal": "30000",
            "discount": "0",
            "tax": "6000",
            "total": "36000"
          }
        }
      ],
      "totals": {
        "subtotal": "30000",
        "tax": "6000",
        "discount": "0",
        "total": "36000",
        "fee": null,
        "credit": "0",
        "balance": "36000",
        "earnings": null,
        "currency_code": "GBP"
      },
      "payout_totals": null,
      "line_items": [
        {
          "id": "txnitm_01gyyw3ja9rt8vh0n0wvyvn59k",
          "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
          "quantity": 10,
          "totals": {
            "subtotal": "30000",
            "tax": "6000",
            "discount": "0",
            "total": "36000"
          },
          "product": {
            "id": "pro_01gsz4t5hdjse780zja8vvr7jg",
            "name": "ChatApp Pro",
            "description": "Everything in basic, plus access to a suite of powerful tools and features designed to take your team's productivity to the next level. Enjoy advanced integrations, improved admin controls, and cross-company chat.",
            "tax_category": "standard",
            "image_url": "https://twemoji.maxcdn.com/v/latest/72x72/2708.png",
            "status": "active"
          },
          "tax_rate": "0.2",
          "unit_totals": {
            "subtotal": "3000",
            "tax": "600",
            "discount": "0",
            "total": "3600"
          }
        }
      ]
    },
    "payments": [],
    "checkout": {
      "url": ""
    }
  },
  "meta": {
    "request_id": "72fba838-5ece-4360-9839-99da4e628207"
  }
}
```

{% /api-example %}

## 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](https://developer.paddle.com/api-reference/transactions/overview.md)
- In webhooks for [transaction events](https://developer.paddle.com/webhooks/transactions/transaction-created.md)

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](https://developer.paddle.com/api-reference/subscriptions/overview.md) using the API.

{% tabs sync="interaction-preference" %}
{% tab-item title="Dashboard" %}

1. Go to **Paddle > Customers**, and find the customer who you created a transaction for.
2. Find the transaction under the Transactions heading and click it.
3. From the transaction overview page, click the box that contains the customer email and address. The box expands to show the full address and any custom data against the transaction.

{% /tab-item %}
{% tab-item title="API" %}

Send a `GET` request to the `/transactions/{transaction_id}` endpoint to get the transaction. Paddle responds with the complete transaction entity including `custom_data`.

{% api-example method="GET" path="/transactions/{transaction_id}" href="/api-reference/transactions/get-transaction" %}

```json
{
  "data": {
    "id": "txn_01gyyw3j6khyc2fpy3ttapzf9v",
    "status": "ready",
    "customer_id": "ctm_01gywfmzk8038netxxbhk80vwe",
    "address_id": "add_01gywfmzn2dwxry2rhry1b5gj4",
    "business_id": null,
    "custom_data": {
      "utm_source": "crm",
      "utm_medium": "email",
      "utm_content": "closed-deal",
      "integration_id": "AA-123"
    },
    "origin": "api",
    "collection_mode": "automatic",
    "subscription_id": null,
    "invoice_id": null,
    "invoice_number": null,
    "billing_details": null,
    "billing_period": null,
    "currency_code": "GBP",
    "discount_id": null,
    "created_at": "2023-04-26T13:30:06.540543605Z",
    "updated_at": "2023-04-26T13:30:06.540543605Z",
    "billed_at": null,
    "items": [
      {
        "price": {
          "id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
          "description": "Monthly (per seat)",
          "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
          "billing_cycle": {
            "interval": "month",
            "frequency": 1
          },
          "trial_period": null,
          "tax_mode": "account_setting",
          "unit_price": {
            "amount": "3000",
            "currency_code": "GBP"
          },
          "unit_price_overrides": [
            {
              "country_codes": ["US"],
              "unit_price": {
                "amount": "4500",
                "currency_code": "USD"
              }
            },
            {
              "country_codes": ["PL"],
              "unit_price": {
                "amount": "8000",
                "currency_code": "PLN"
              }
            },
            {
              "country_codes": ["IN"],
              "unit_price": {
                "amount": "100500",
                "currency_code": "INR"
              }
            },
            {
              "country_codes": ["UA"],
              "unit_price": {
                "amount": "40000",
                "currency_code": "UAH"
              }
            },
            {
              "country_codes": ["NG"],
              "unit_price": {
                "amount": "1400",
                "currency_code": "USD"
              }
            }
          ],
          "quantity": {
            "minimum": 10,
            "maximum": 999
          },
          "status": "active"
        },
        "quantity": 10
      }
    ],
    "details": {
      "tax_rates_used": [
        {
          "tax_rate": "0.2",
          "totals": {
            "subtotal": "30000",
            "discount": "0",
            "tax": "6000",
            "total": "36000"
          }
        }
      ],
      "totals": {
        "subtotal": "30000",
        "tax": "6000",
        "discount": "0",
        "total": "36000",
        "fee": null,
        "credit": "0",
        "balance": "36000",
        "earnings": null,
        "currency_code": "GBP"
      },
      "payout_totals": null,
      "line_items": [
        {
          "id": "txnitm_01gyyw3ja9rt8vh0n0wvyvn59k",
          "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
          "quantity": 10,
          "totals": {
            "subtotal": "30000",
            "tax": "6000",
            "discount": "0",
            "total": "36000"
          },
          "product": {
            "id": "pro_01gsz4t5hdjse780zja8vvr7jg",
            "name": "ChatApp Pro",
            "description": "Everything in basic, plus access to a suite of powerful tools and features designed to take your team's productivity to the next level. Enjoy advanced integrations, improved admin controls, and cross-company chat.",
            "tax_category": "standard",
            "image_url": "https://twemoji.maxcdn.com/v/latest/72x72/2708.png",
            "status": "active"
          },
          "tax_rate": "0.2",
          "unit_totals": {
            "subtotal": "3000",
            "tax": "600",
            "discount": "0",
            "total": "3600"
          }
        }
      ]
    },
    "payments": [],
    "checkout": {
      "url": ""
    }
  },
  "meta": {
    "request_id": "f18ef701-42c7-476c-9083-34e36e59e920"
  }
}
```

{% /api-example %}

{% /tab-item %}
{% /tabs %}

## Update or remove custom data

You can update or remove custom data against a transaction or subscription using the API.

{% accordion %}
{% accordion-item title="Transactions" %}

{% callout type="info" %}
Transactions are financial records. You can't edit them if they're billed, canceled, or completed.
{% /callout %}

Send a `PATCH` request to the `/transactions/{transaction_id}` endpoint, including `custom_data` as a JSON object.

To remove custom data, set `custom_data` to `null`.

{% api-example method="PATCH" path="/transactions/{transaction_id}" href="/api-reference/transactions/update-transaction" %}

```json
{
  "custom_data": {
    "integration_id": "BB-456"
  }
}
```

{% /api-example %}

{% /accordion-item %}
{% accordion-item title="Subscriptions" %}

Send a `PATCH` request to the `/subscriptions/{subscription_id}` endpoint, including `custom_data` as a JSON object. To remove custom data, set `custom_data` to `null`.

{% api-example method="PATCH" path="/subscriptions/{subscription_id}" href="/api-reference/subscriptions/update-subscription" %}

```json
{
  "custom_data": {
    "integration_id": "BB-456"
  }
}
```

{% /api-example %}

{% /accordion-item %}
{% /accordion %}