For AI agents and LLMs: a structured documentation index is available at /llms.txt. Every page has a Markdown sibling — append .md to any URL.

Skip to content
Docs

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.

AI summary

Custom data lets you attach arbitrary JSON key-value pairs to most Paddle entities — such as products, customers, and subscriptions — to pass metadata through to third-party systems like CRMs or analytics platforms.

  • • Custom data must be valid JSON and must include at least one key; it is returned in API responses, webhook payloads, and the Paddle dashboard.
  • • Add custom_data to products, prices, discounts, transactions, subscriptions, customers, addresses, and businesses via create or update requests.
  • • Custom data added to a checkout via Paddle.js is stored against the related transaction, and also against the subscription if the checkout includes recurring items.

Custom data lets you add your own structured key-value data when working with most 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.
  • For most entities, in the Paddle dashboard.

Use custom data to pass information through to third-party integrations like a CRM or analytics platform.

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:

POST /products
Request
{
  "name": "AeroEdit Student",
  "tax_category": "standard",
  "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.",
  "image_url": "https://paddle.s3.amazonaws.com/user/165798/bT1XUOJAQhOUxGs83cbk_pro.png",
  "custom_data": {
    "features": {
      "aircraft_performance": true,
      "compliance_monitoring": false,
      "flight_log_management": true,
      "payment_by_invoice": false,
      "route_planning": true,
      "sso": false
    },
    "suggested_addons": [
      "pro_01h1vjes1y163xfj1rh1tkfb65",
      "pro_01gsz97mq9pa4fkyy0wqenepkz"
    ],
    "upgrade_description": null
  }
}
Response (201)
{
  "data": {
    "id": "pro_01htz88xpr0mm7b3ta2pjkr7w2",
    "name": "AeroEdit Student",
    "tax_category": "standard",
    "type": "standard",
    "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.",
    "image_url": "https://paddle.s3.amazonaws.com/user/165798/bT1XUOJAQhOUxGs83cbk_pro.png",
    "custom_data": {
      "features": {
        "aircraft_performance": true,
        "compliance_monitoring": false,
        "flight_log_management": true,
        "payment_by_invoice": false,
        "route_planning": true,
        "sso": false
      },
      "suggested_addons": [
        "pro_01h1vjes1y163xfj1rh1tkfb65",
        "pro_01gsz97mq9pa4fkyy0wqenepkz"
      ],
      "upgrade_description": null
    },
    "status": "active",
    "import_meta": null,
    "created_at": "2024-04-08T16:22:16.024Z",
    "updated_at": "2024-04-08T16:22:16.024Z"
  },
  "meta": {
    "request_id": "cf40234b-e140-44d1-a83f-7bbdedd88589"
  }
}

Add using the checkout

To add custom data when opening a checkout using Paddle.js, pass customData in the Paddle.Checkout.open() call:

Paddle.js example
Paddle.Checkout.open({
  settings: {
    displayMode: "overlay",
    theme: "light",
    locale: "en"
  },
  customData: {
    "crm_id": 1234,
    "utm_source": "google"
  },
  items: [
    {
      priceId: 'pri_01gm81eqze2vmmvhpjg13bfeqg',
      quantity: 1
    },
    {
      priceId: 'pri_01gm82kny0ad1tk358gxmsq87m',
      quantity: 1
    },
    {
      priceId: 'pri_01gm82v81g69n9hdb0v9sw6j40',
      quantity: 1
    }
  ],
  customer: {
    email: "sam@example.com",
    address: {
      countryCode: "US",
      postalCode: "10021"
    },
    business: {
      name: "ChatApp Inc",
      taxIdentifier: "802311782"
    }
  }
});

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.

Was this page helpful?