Custom data

Custom data lets you attach your own data when working with invoices in the Paddle Invoice API. Paddle accepts key-value pairs for custom data, which makes it easy to work with using the API.

Once attached, custom data is accessible in the Paddle dashboard, returned by the API, and included in webhook responses.

It’s great for adding information that you might want to pass through to third-party integrations, like a CRM or analytics solution.

Add using the API

To add custom data to an entity using the API, include a custom_data object when creating or updating entities.

For example:

{
  "custom_data": {
    "internal_user_id": 456098,
    "active": true
  },
  "customer_id": "ctm_31kmsg7LfRKYp19gtRLtkn",
  "address_id": "add_39lmJsg0LfRNOp15btRLtkn",
  "business_id": "biz_27lmJsg0LfRNOp15btRLtkn",
  "currency_code": "USD",
  "billing_details": {
    "enable_checkout": true,
    "purchase_order_number": "PO-999",
    "additional_information": "Contact your sales rep if you have any problems.",
    "payment_terms": {
      "interval": "day",
      "frequency": 30
    }
  },
  "billing_period": {
    "type": "billing",
    "starts_at": "2023-10-15",
    "ends_at": "2023-11-15"
  },
  "items": [
    {
      "price": {
        "unit_price": {
          "amount": "string",
          "currency_code": "USD"
        }
      },
      "quantity": 1
    }
  ]
}

Get custom data

If you’ve attached custom data to an entity, the Paddle Invoice API and webhooks return it when you query an entity.

For example:

{
  "data": {
    "custom_data": {
      "internal_user_id": 456098,
      "active": true
    },
    "id": "inv_01ghbk4xjn4qdsmstcwzgcgg35",
    "status": "paid",
    "customer_id": "ctm_31kmsg7LfRKYp19gtRLtkn",
    "address_id": "add_39lmJsg0LfRNOp15btRLtkn",
    "business_id": "biz_27lmJsg0LfRNOp15btRLtkn",
    "invoice_number": "123-45678",
    "currency_code": "USD",
    "billing_details": {
      "enable_checkout": true,
      "purchase_order_number": "PO-999",
      "additional_information": "Contact your sales rep if you have any problems.",
      "payment_terms": {
        "interval": "day",
        "frequency": 30
      }
    },
    "billing_period": {
      "type": "billing",
      "starts_at": "2023-10-15",
      "ends_at": "2023-11-15"
    },
    "items": [
      {
        "price": {
          "unit_price": {
            "amount": "string",
            "currency_code": "USD"
          },
          "product_id": "pro_71jbvv7LfRKYp19gtRLtkn"
        },
        "quantity": 1
      }
    ],
    "details": {
      "totals": {
        "subtotal": "15000",
        "tax": "1500",
        "total": "16500"
      },
      "line_items": [
        {
          "quantity": 1,
          "tax_rate": "Sales Tax",
          "unit_totals": {
            "subtotal": "15000",
            "tax": "1500",
            "total": "16500"
          },
          "totals": {
            "subtotal": "15000",
            "tax": "1500",
            "total": "16500"
          },
          "product": {
            "id": "pro_71jbvv7LfRKYp19gtRLtkn",
            "name": "Premium Plan",
            "description": "Everything in Basic, plus advanced marketing automation and reporting.",
            "tax_category": "standard",
            "image_url": "https://cdn.paddle.com/products/pro_71jbvv7L.png",
            "status": "active",
            "created_at": "2023-10-12T07:20:50.52Z",
            "custom_data": {}
          }
        }
      ]
    },
    "checkout": "2023-10-12T07:20:50.52Z",
    "updated_at": "2023-10-12T07:20:50.52Z",
    "issued_at": "2023-10-12T07:20:50.52Z",
    "paid_at": "2023-10-12T07:20:50.52Z",
    "due_at": "2023-10-12T07:20:50.52Z"
  }
}

Update custom data

Send a PATCH request to update custom_data.

For example:

{
  "custom_data": {
    "internal_user_id": 456098,
    "active": false
  }
}