Overview

Products are objects containing variants. When a customer purchases a product, they are sent the respetive deliverable(s) that product's variant contains.

One product can have many variants, each of which have their own price, product deliverable, and pricing.

On this page, we'll dive into the different product endpoints you can use to manage products - and product variants - programmatically. We'll look at how to create, update, and delete products.

Endpoints

• List all products
• Create a product
• Retrieve a product
• Update a product
• Delete a product

The product model

The product model contains all the information about the products stores have, including the price, media, and customization options.

Properties

Field Type Details

Text Input Fields

text

Single-line text input with optional placeholder.

Supported properties: placeholder, description Max length: 255 characters

Example:

{
  "type": "text",
  "label": "In-Game Username",
  "required": true,
  "placeholder": "Enter your username",
  "description": "Must match your game account"
}

number

Numeric input with range validation.

Supported properties: placeholder, description Range: -9,007,199,254,740,991 to 9,007,199,254,740,991

Example:

{
  "type": "number",
  "label": "Quantity",
  "required": true,
  "placeholder": "0"
}

email

Email input.

Supported properties: placeholder, description Max length: 255 characters

Example:

{
  "type": "email",
  "label": "Recovery Email",
  "required": false,
  "placeholder": "user@example.com",
  "description": "For account recovery"
}

phone

Phone number input with country selector.

Supported properties: description Max length: 25 characters Format: Automatically normalized to E.164 (+1234567890)

Example:

{
  "type": "phone",
  "label": "Mobile Number",
  "required": true,
  "description": "For SMS delivery notifications"
}

currency

Currency amount with currency selector.

Supported properties: description Format: Stores amount in minor units (cents) with currency code

Example:

{
  "type": "currency",
  "label": "Budget",
  "required": true,
  "description": "Your maximum budget"
}

link

URL input with validation. Automatically prepends https:// if missing.

Supported properties: placeholder, description Max length: 2048 characters

Example:

{
  "type": "link",
  "label": "Portfolio Website",
  "required": false,
  "placeholder": "https://example.com"
}

textarea

Multi-line text input.

Supported properties: placeholder, description Max length: 2048 characters

Example:

{
  "type": "textarea",
  "label": "Special Instructions",
  "required": false,
  "placeholder": "Enter any special requirements...",
  "description": "Tell us about customization needs"
}

Selection Fields

Selection fields require an options array and support two formats:

Simple format (string array):

"options": ["Option A", "Option B", "Option C"]

Enhanced format (objects with metadata): Only supported for radio, checkbox-group, and switch (fieldset variant).

"options": [
{
"label": "Basic Plan",
"value": "basic",
"description": "Perfect for individuals"
},
{
"label": "Pro Plan",
"value": "pro",
"description": "Designed for teams"
}
]

Enhanced option properties:

• label (required) - Display text (1-100 characters)
• value (optional) - Stored value (defaults to label if omitted)
• description (optional) - Helper text (max 255 characters, only displays in compatible variants)

select

Dropdown selection field.

Supported properties: placeholder, description, variant, options (required) Options format: String array only

Variants:

• single (default) - Single selection
• multiple - Multiple selection

Example:

{
  "type": "select",
  "label": "Preferred Region",
  "required": true,
  "variant": "single",
  "options": [
    "North America",
    "Europe",
    "Asia"
  ],
  "placeholder": "Select your region..."
}

radio

Radio button group for single selection.

Supported properties: description, variant (required), options (required) Options format: String array or enhanced objects (for default and cards variants)

Variants:

• default - Standard radio buttons (supports descriptions)
• cards - Card-style options (supports descriptions)
• row - Inline horizontal layout
• pills - Pill-shaped options
• buttons - Button-style options
• segmented - Segmented control

Example with enhanced options:

{
  "type": "radio",
  "label": "Subscription Plan",
  "required": true,
  "variant": "cards",
  "options": [
    {
      "label": "Starter",
      "value": "starter",
      "description": "$9/month - For individuals"
    },
    {
      "label": "Pro",
      "value": "pro",
      "description": "$29/month - For teams"
    }
  ]
}

checkbox-group

Checkbox group for multiple selections.

Supported properties: description, variant (required), options (required) Options format: String array or enhanced objects (for default and cards variants)

Variants:

• default - Standard checkboxes (supports descriptions)
• cards - Card-style checkboxes (supports descriptions)
• fieldset - Horizontal inline group
• pills - Pill-shaped checkboxes
• buttons - Button-style checkboxes

Example:

{
  "type": "checkbox-group",
  "label": "Add-on Services",
  "required": false,
  "variant": "default",
  "options": [
    "Gift Wrapping",
    "Express Shipping",
    "Insurance"
  ]
}

pillbox

Multi-select with removable pill-shaped tags.

Supported properties: placeholder, description, options (required) Options format: String array only

Example:

{
  "type": "pillbox",
  "label": "Programming Languages",
  "required": true,
  "options": [
    "JavaScript",
    "Python",
    "Java",
    "Go"
  ],
  "placeholder": "Choose languages..."
}

Boolean Fields

checkbox

Single yes/no checkbox.

Supported properties: description

Example:

{
  "type": "checkbox",
  "label": "I agree to the Terms of Service",
  "required": true,
  "description": "You must accept to proceed"
}

switch

Toggle switch (on/off).

Supported properties: description, variant (required) Options: Only required for fieldset variant (supports enhanced format)

Variants:

• single - Single on/off toggle
• fieldset - Multiple switches in a group (requires options)

Important: Switch fields are typically not required because they represent on/off states where "off" (false) is a valid value. While you can technically set required: true, it rarely makes semantic sense for a toggle.

Example - Single:

{
  "type": "switch",
  "label": "Enable Notifications",
  "required": false,
  "variant": "single"
}

Example - Fieldset:

{
  "type": "switch",
  "label": "Privacy Settings",
  "required": false,
  "variant": "fieldset",
  "options": [
    {
      "label": "Profile Visibility",
      "value": "profile_public",
      "description": "Make profile public"
    },
    {
      "label": "Activity Feed",
      "value": "show_activity",
      "description": "Display recent activity"
    }
  ]
}

Date Fields

Date fields support advanced configuration via the date_options object:

Common date_options properties:

• min_date (string) - Minimum date: "today" or "YYYY-MM-DD"
• max_date (string) - Maximum date: "today" or "YYYY-MM-DD"
• start_day (integer) - First day of week (0=Sunday, 1=Monday, ..., 6=Saturday, default: 1)
• clearable (boolean) - Show clear button (default: false)
• week_numbers (boolean) - Display week numbers (default: false)
• selectable_header (boolean) - Clickable month/year header (default: false)

Additional properties for date-range:

• min_range (integer) - Minimum range in days (≥1)
• max_range (integer) - Maximum range in days (≥1)
• with_presets (boolean) - Show preset buttons (default: false)
• with_inputs (boolean) - Show date inputs (default: false)
• presets (string) - Space-separated preset list

Available presets: today, yesterday, thisWeek, lastWeek, last7Days, last14Days, last30Days, thisMonth, lastMonth, last3Months, last6Months, thisQuarter, lastQuarter, thisYear, lastYear, yearToDate

date

Single date picker.

Supported properties: placeholder, description, date_options

Example:

{
  "type": "date",
  "label": "Delivery Date",
  "required": true,
  "placeholder": "Select a date...",
  "date_options": {
    "min_date": "today",
    "max_date": "2025-12-31",
    "start_day": 1,
    "clearable": true
  }
}

date-range

Date range picker.

Supported properties: placeholder, description, date_options

Example:

{
  "type": "date-range",
  "label": "Rental Period",
  "required": true,
  "placeholder": "Select rental period...",
  "description": "Minimum 3 days, maximum 30 days",
  "date_options": {
    "min_date": "today",
    "max_date": "2026-06-30",
    "min_range": 3,
    "max_range": 30,
    "start_day": 1,
    "clearable": true,
    "with_presets": true,
    "presets": "last7Days last14Days last30Days thisMonth"
  }
}

Special Fields

hidden

Hidden field not visible to customers.

Supported properties: None Note: Still requires a label for internal identification.

Example:

{
  "type": "hidden",
  "label": "Campaign Source",
  "required": false,
  "key": "utm_source"
}

Validation Rules

Field-Level Validation

• type - Must be a valid field type from the supported list
• label - Required, 2-100 characters, must be unique, cannot use reserved names
• required - Required, must be boolean
• key - Optional, 2-100 characters, letters and underscores only, must be unique
• placeholder - Optional, 2-255 characters (only for supported field types)
• description - Optional, 2-255 characters (only for supported field types)
• options - Required for select, radio, checkbox-group, pillbox. Required for switch with fieldset variant
• variant - Required for select, radio, checkbox-group, switch. Must be valid variant for the field type

Reserved Field Labels

These labels are reserved and cannot be used:

• purchase_quantity
• customer_email
• payment_method
• extra

Options Validation

String options:

• Each option: 1-100 characters

Enhanced options (objects):

• label - Required, 1-100 characters
• value - Optional, 1-100 characters (defaults to label)
• description - Optional, max 255 characters

Date Options Validation

• min_date / max_date - Must be "today" or valid YYYY-MM-DD format
• min_date must be ≤ max_date when both are specific dates
• start_day - Integer 0-6
• min_range / max_range - Positive integers ≥1
• min_range must be ≤ max_range
• Boolean options must be true or false
• presets - Space-separated string of valid preset values