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.

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?