Seasons Tools
View and create pricing seasons. Seasons define date ranges, time-of-day ranges, or day-of-week rules that are used for seasonal pricing on products and experiences.
Required scope: settings:read for listing, settings:write for creating
Tools Overview
| Tool | Description | Read-only? |
|---|---|---|
list_seasons | List pricing seasons | Yes |
create_season | Create a new pricing season | No |
list_seasons
List pricing seasons configured for the business. Seasons define when seasonal pricing rules apply.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
type | string | No | Filter by season type: date, time, days |
Season Types
| Type | Description | Example |
|---|---|---|
date | One or more date ranges | Regular: Jun 1 – Aug 31 and Dec 1 – Dec 20 |
time | Time-of-day range | Evening: 5:00 PM - 9:00 PM |
days | Days of the week | Weekends: Saturday, Sunday |
For date seasons, each item includes a date_ranges array — a season can cover
several stretches of the year. start_date / end_date are also returned for
backward compatibility and equal the first range.
create_season
Create a new pricing season. Requires the Pro plan. Requires user confirmation before creation.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Season name (e.g., "Summer", "Weekend Peak") |
type | string | Yes | Season type: date, time, or days |
start_date | string | No | Start date YYYY-MM-DD. Single-range shorthand for date type (use date_ranges for several). |
end_date | string | No | End date YYYY-MM-DD. Single-range shorthand for date type. |
date_ranges | object[] | No | One or more date ranges for a date season, each { "start_date": "YYYY-MM-DD", "end_date": "YYYY-MM-DD" }. Use this for a season covering several stretches of the year. If omitted, start_date/end_date are used as a single range. |
start_time | string | No | Start time HH:MM (required for time type) |
end_time | string | No | End time HH:MM (required for time type) |
applicable_days | string[] | No | Days this season applies to (e.g., ["monday", "tuesday"]). Defaults to all 7 days. |
user_confirmed | boolean | Yes | Must be true to create the season |
The AI assistant will describe the season details and ask for confirmation before calling this tool with user_confirmed: true.
Required Fields by Type
| Type | Required Fields |
|---|---|
date | date_ranges (or start_date + end_date for a single range) |
time | start_time, end_time |
days | applicable_days |
Related
- Settings REST API - REST API for seasons configuration
- Products Tools - Products that use seasonal pricing
- Experiences Tools - Experiences that use seasonal pricing