Seasonal Pricing

GET/boats/:id/prices

Retrieve all seasonal pricing rules for a boat, ordered by priority (highest first), then by start month.

Path Parameters

Parameter	Type	Description
`id`	string	Boat ID (UUID)

Request

curl https://charter.boats/api/boats/550e8400-e29b-41d4-a716-446655440000/prices

Response

Returns an array of price objects.

[
  {
    "id": "a1b2c3d4-...",
    "boat_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Peak Price",
    "start_month": 6,
    "start_day": 1,
    "end_month": 8,
    "end_day": 31,
    "price_per_day": 500,
    "priority": 1,
    "source": "direct",
    "source_id": null,
    "original_price_per_day": null,
    "discount_percentage": null,
    "discount_name": null,
    "valid_from_year": null,
    "valid_to_year": null,
    "created_at": "2024-01-15T10:00:00Z"
  },
  {
    "id": "e5f6a7b8-...",
    "boat_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Off Price",
    "start_month": 11,
    "start_day": 1,
    "end_month": 3,
    "end_day": 31,
    "price_per_day": 300,
    "priority": 0,
    "source": "direct",
    "source_id": null,
    "original_price_per_day": null,
    "discount_percentage": null,
    "discount_name": null,
    "valid_from_year": null,
    "valid_to_year": null,
    "created_at": "2024-01-15T10:00:00Z"
  }
]

Response Fields

Field	Type	Description
`id`	string	Price ID (UUID)
`boat_id`	string	Boat this price belongs to
`name`	string	Price name
`start_month`	integer	Start month (1-12)
`start_day`	integer	Start day (1-31)
`end_month`	integer	End month (1-12)
`end_day`	integer	End day (1-31)
`price_per_day`	number	Daily rate for this price
`priority`	integer	Higher priority wins on overlaps (default: 0)
`source`	string	Pricing source (`direct`, `nausys`, or `mmk`)
`source_id`	string \| null	External source identifier
`original_price_per_day`	number \| null	Pre-discount price (if a discount applies)
`discount_percentage`	number \| null	Active discount percentage
`discount_name`	string \| null	Name of the discount
`valid_from_year`	integer \| null	Year the price starts applying
`valid_to_year`	integer \| null	Year the price stops applying
`created_at`	string	ISO 8601 timestamp

Prices can wrap around year boundaries (e.g., November 15 to January 15).

Create Price

POST/boats/:id/prices

Create a new seasonal pricing rule. Requires authentication as a company member for the boat.

Authentication

X-API-Key: cb_live_xxxxx

Request Body

Field	Type	Required	Description
`name`	string	Yes	Price name (e.g., "Peak Price")
`start_month`	integer	Yes	Start month (1-12)
`start_day`	integer	Yes	Start day (1-31)
`end_month`	integer	Yes	End month (1-12)
`end_day`	integer	Yes	End day (1-31)
`price_per_day`	number	Yes	Daily rate for this price
`priority`	integer	No	Higher priority wins on overlaps (default: 0)

Request

curl -X POST https://charter.boats/api/boats/550e8400-e29b-41d4-a716-446655440000/prices \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cb_live_xxxxx" \
  -d '{
    "name": "Holiday Price",
    "start_month": 12,
    "start_day": 20,
    "end_month": 1,
    "end_day": 5,
    "price_per_day": 600,
    "priority": 2
  }'

Response

Returns the created price object.

{
  "id": "c3d4e5f6-...",
  "boat_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Holiday Price",
  "start_month": 12,
  "start_day": 20,
  "end_month": 1,
  "end_day": 5,
  "price_per_day": 600,
  "priority": 2,
  "source": "direct",
  "source_id": null,
  "original_price_per_day": null,
  "discount_percentage": null,
  "discount_name": null,
  "valid_from_year": null,
  "valid_to_year": null,
  "created_at": "2024-01-20T14:30:00Z"
}

Errors

Status	Message
`400`	Name, start/end dates, and price are required
`400`	Month must be between 1 and 12
`400`	Day must be between 1 and 31
`404`	Boat not found

Price Resolution

When multiple prices overlap, the one with the highest priority value wins. If no price covers a date, the date is considered unavailable.

Priority order:

Date-specific overrides (highest)
Seasonal pricing (by priority)
No coverage = unavailable

Seasonal Pricing

On this page