Skip to main content
The Number field only accepts number entries (integers and decimals) and returns a JSON number in the API, which makes it perfect for prices, quantities, and dimensions. Number field configuration in ButterCMS
Always use the Number field for numeric data instead of Short Text. This ensures proper type validation and returns the correct data type in your API response.

​
Field at a glance

​
Input and output

Input type

Numbers (integers, decimals, and floats)

API output

number

​
API response example

"temperature": -15.5

​
Field configuration options

Use help text and default values to guide your content teams.
Option NameTypeFunction
Required?booleanMake field required to save page
Default valuestringSet a default value for the field

​
Common use cases

E-commerce
  • Product prices
  • Stock quantities
  • Shipping weights
  • Discount percentages
  • Order totals
Events and scheduling
  • Event capacity
  • Number of attendees
  • Duration in minutes/hours
  • Room numbers
Content metrics
  • Read time estimates
  • View counts
  • Rating scores
  • Sort order/priority
Configuration values
  • Display order
  • Maximum items to show
  • Pagination limits

​
Handling different number types

​
Integers

Number fields support integers (numbers without a decimal), including both zero and negative integers. 
{
  "quantity": 100,
  "rating": 5,
  "order_number": 12345
}

{
  "wind_speed": 0,
  "temperature": -5,
}

​
Decimals (floats)

Number fields support decimal/float values with no restriction on the number of places after the decimal. This includes both 0.00 and negative numbers. 
{
  "price": 29.99,
  "discount_percentage": 0.5,
  "weight_kg": 2.75,
  "temperature": -15.5
}

​
Large numbers

Be aware of JavaScript’s number precision limits for very large numbers: 
// Safe integer range in JavaScript
console.log(Number.MAX_SAFE_INTEGER); // 9007199254740991

// For larger numbers, consider storing as strings
// and using BigInt in your application

​
Number field vs. Short Text for numbers

Always use the Number field for numeric data instead of Short Text. This ensures proper type validation and returns the correct data type in your API response.
// Number field
{ "price": 29.99 }

// Short Text (incorrect approach)
{ "price": "29.99" }
AspectNumber FieldShort Text
API outputnumber"string"
ValidationBuilt-in numeric validationManual regex needed
Math operationsWorks directlyRequires parsing
SortingCorrect numeric sortAlphabetical sort

​
Best practices

​
Prices

  • Consider your currency’s decimal precision
  • Use help text to specify the expected currency

​
Quantities

  • Use integers only (no decimals)
  • Use help text to clarify expected values

​
Percentages

  • Clarify in help text whether to enter as 15 or 0.15 for 15%

​
Ratings

  • Consider using a dropdown for consistent values

​
Working with numbers in your application

​
JavaScript example

// Fetching and using number fields
const butter = require('buttercms')('your-api-key');

const response = await butter.page.retrieve('*', 'product-page');
const product = response.data.data.fields;

// Numbers are returned as actual numbers, not strings
const price = product.price; // 29.99 (number)
const quantity = product.stock_quantity; // 100 (number)

// Format for display
const formattedPrice = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD'
}).format(price); // "$29.99"

// Math operations work directly
const total = price * quantity; // 2999

​
Python example

from butter_cms import ButterCMS

client = ButterCMS('your-api-key')

response = client.pages.get('*', 'product-page')
product = response['data']['fields']

# Numbers are Python floats/ints
price = product['price']  # 29.99
quantity = product['stock_quantity']  # 100

# Format for display
formatted_price = f"${price:,.2f}"  # "$29.99"

# Math operations
total = price * quantity  # 2999.0