Create a property definition

POST

/v1/property_definitions

curl -X POST "https://api.summerbase.com/v1/property_definitions" \
  -H "Authorization: Bearer sb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "key": "seats",
    "label": "Seats",
    "subject_type": "customer",
    "value_type": "number"
  }'

Declare a key before anything writes it, so the first value arrives with a type already decided.

Worth doing for a key whose values come from a provider, where everything is a string: declaring seats a number here is what makes a range filter on it work later. The key lands in your own source’s namespace.

Parameters

Query Parameters

expand[]

Array<string>

<= 10 items

Allowed values: source

Relationships to include in the response instead of fetching separately. A dotted path expands what an expanded record can expand in turn — at most 4 deep, 10 paths a request, and never back to a record already on the path.

Request Body^required

Media typeapplication/json

object

key

required

The key, as written. Immutable once it exists.

string

>= 1 characters <= 255 characters

label

What a screen calls this property: the name the source that owns it gave it, or the key in words — deal_stage is Deal Stage.

string

>= 1 characters <= 255 characters

subject_type

required

What kind of record this key describes.

string

Allowed values: customer subscription subscription_item plan price

value_type

required

What values of this key hold, fixed by the first one written.

string

Allowed values: string number boolean datetime

Example

{
  "key": "seats",
  "label": "Seats",
  "subject_type": "customer",
  "value_type": "number"
}

Response

Returns the property definition object.

Media typeapplication/json

Example

{
  "archived": false,
  "created_at": "2026-02-11T09:20:13Z",
  "id": "0198f1a5-7a8b-7c9d-8e0f-1a2b3c4d5e6f",
  "key": "seats",
  "label": "Seats",
  "object": "property_definition",
  "source_id": "0198f1a3-0c18-7d93-a6e2-1b4f9d7c3a58",
  "subject_type": "customer",
  "value_type": "number"
}