Data types
Make requests to the Paddle API in JSON. Paddle responds in JSON.
The Paddle API uses JSON formatted data for requests and responses.
When making requests, specify application/json as your Content-Type. For example:
12341curl -X POST https://api.paddle.com/customers
2 -H "Authorization: Bearer bb4e69088ea07a98a90565ac610c63654423f8f1e2d48b39b5"
3 -H "Content-Type: application/json"
4 -d "{ "name": "Sam Miller", "email": "sam@example.com" }"Paddle always sends responses as JSON. This includes errors as well as success responses.
Dates and times
All dates and times use the RFC 3339 format. For example:
| Time and date | RFC 3339 |
|---|---|
| 3:30pm on March 20th 2024 | 2024-03-20T15:30:00.00Z |
| 2am on January 12th 2025 | 2025-01-12T02:00:00.00Z |
| 8:50pm on October 12th 2025 | 2025-10-12T20:50:00.00Z |
Timezones
Paddle supports over 200 countries, so dates and times are UTC.
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:
| Currency | Decimals | Example | Value |
|---|---|---|---|
USD | 2 | $24.99 | "2499" |
JPY | 0 | ¥1000 | "1000" |
We recommend using a currency library to format monetary values to the correct number of decimals. They can also help you format values for different locales and currency standards, making sure that currency symbols are placed correctly and the correct decimal separator is used.
For convenience, the preview prices operation returns formatted_unit_totals and formatted_totals objects alongside objects that return totals in the lowest denomination for a currency. Formatted totals objects return values formatted for the country or region you're working with, including the currency symbol.
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.
