Data types

The Paddle API uses JSON for requests and responses.

When making requests, specify application/json as your Content-Type. For example:

curl -X POST https://api.paddle.com/customers \
  -H "Authorization: Bearer pdl_live_apikey_01gtgztp8f4kek3yd4g1wrksa3_q6TGTJyvoIz7LDtXT65bX7_AQO" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Sam Miller", "email": "sam@example.com" }'

Paddle always returns responses as JSON. This includes errors as well as success responses.

Dates and times

All dates and times use the RFC 3339 format and are returned in UTC. For example:

Booleans

Boolean fields accept true or false. Paddle doesn't coerce strings like "true" or 1 pass the JSON boolean.

Null values

null is a valid value for nullable fields. Setting a field to null in a PATCH request clears the value. Omitting the field leaves the existing value unchanged.

Currency codes

Currency codes follow ISO 4217 and are three-letter uppercase strings like USD, GBP, or JPY. See Supported currencies for the full list.

Money

Monetary values are returned as strings in the lowest denomination for a currency. For example, the API returns values in cents for USD and pence for GBP.

Many currencies have two decimals, but this can vary. For example:

Use a currency library to format monetary values to the correct number of decimals. Currency libraries also help format values for different locales, making sure symbols and decimal separators are placed correctly.

For convenience, the preview prices operation returns formatted_unit_totals and formatted_totals objects alongside objects that return totals in the lowest denomination. Formatted totals include the currency symbol and are formatted for the country or region you're working with.

For a full list of supported currencies and their decimals, see Supported currencies.

Custom data

You can add custom data to some entities in Paddle. Custom data must be valid JSON.