Custom data
Attach arbitrary key-value data to entities in Paddle when working with the API or checkout. Typically used for storing metadata or other useful information when working with third-party solutions.
Custom data lets you add your own structured key-value data when working with some entities in Paddle. You can add it when working with the checkout or when creating or updating entities using the API.
Once added, you can see custom data:
- When getting an entity or listing entities using the API.
- In webhook responses.
- In the Paddle dashboard against an entity — some entities only.
It's great for adding information that you might want to pass through to third-party integrations, like a CRM or analytics solution.
Custom data must be valid JSON, and you must provide at least one key.
Add or update using the API
You can add custom data to:
To add custom data to an entity using the API, include a custom_data object when creating or updating entities.
For example, to add custom data when creating a product:
12345678910111213141516171819201{
2 "name": "AeroEdit Student",
3 "tax_category": "standard",
4 "description": "Essential tools for student pilots to manage flight logs, analyze performance, and plan routes, and ensure compliance. Valid student pilot certificate from the FAA required.",
5 "image_url": "https://paddle.s3.amazonaws.com/user/165798/bT1XUOJAQhOUxGs83cbk_pro.png",
6 "custom_data": {
7 "features": {
8 "aircraft_performance": true,
9 "compliance_monitoring": false,
10 "flight_log_management": true,
11 "payment_by_invoice": false,
12 "route_planning": true,
13 "sso": false
14 },
15 "suggested_addons": [
16 "pro_01h1vjes1y163xfj1rh1tkfb65",
17 "pro_01gsz97mq9pa4fkyy0wqenepkz"
18 ],
19 "upgrade_description": null
20 }
Add using the checkout
To add custom data when opening a checkout using Paddle.js, pass customData in the Paddle.Checkout.open() method call:
12345678910111213141516171819201Paddle.Checkout.open({
2 settings: {
3 displayMode: "overlay",
4 theme: "light",
5 locale: "en"
6 },
7 customData: {
8 "crm_id": 1234,
9 "utm_source": "google"
10 },
11 items: [
12 {
13 priceId: 'pri_01gm81eqze2vmmvhpjg13bfeqg',
14 quantity: 1
15 },
16 {
17 priceId: 'pri_01gm82kny0ad1tk358gxmsq87m',
18 quantity: 1
19 },
20 {
Any custom data against a checkout is against the related transaction. If a checkout is for recurring items, it's stored against the created subscription, too.
