---
title: "Create a new Rate Plan."
method: POST
path: "/rates/v1/rate-plans"
tags: ["Rate Plans"]
---

# Create a new Rate Plan.

`POST /rates/v1/rate-plans`

## Request

- Base URL: `https://api.cloudbeds.com`
- URL: `https://api.cloudbeds.com/rates/v1/rate-plans`
- Auth: OAuth 2
  - Authorization code: `https://api.cloudbeds.com/auth/oauth/authorize`
  - Token URL: `https://api.cloudbeds.com/auth/oauth/token` scopes: `write:rate`

## Headers

- `x-property-id` string, required

## Request body

- RatePlanCreateRequestSchema
  - `isActive` boolean, required: The status of the rate plan.
  - `roomTypeId` integer, required: The room type ID assigned to this rate plan.
  - `name` object, required: Name in multiple languages.
  - `description` object, required: Description in multiple languages.
  - `namePrivate` object, required: Internal name in multiple languages.
  - `allotmentBlockId` string, nullable: The allotment block's ID this rate belongs to.
  - `promoCode` string, nullable: Promotional code for the rate plan.
  - `sources` string[], nullable: List of sources for the rate plan.
  - `derivedValue` number, float, nullable: Value for the derived rate plan.
  - `derivedRatePlanId` integer, nullable: Derived rate plan ID.
  - `derivedType` 'fixed' | 'percentage': Rate plan derived type.
  - `terms` object, nullable: Terms and conditions in multiple languages.
  - `intervals` RatePlanIntervalRequestSchema[], nullable: List of rate plan intervals.
    - `startDate` string, date, required: Start date of the interval.
    - `endDate` string, date, required: End date of the interval.
    - `name` string, required: Name of the interval.
    - `roomTypeId` string: Room type ID.
    - `minLos` integer, nullable: Minimum length of stay.
    - `maxLos` integer, nullable: Maximum length of stay.
    - `eventCode` string, nullable: Event code.
    - `days` object, nullable: Days of the week pricing (0=Sunday, 1=Monday, etc.).
    - `adultDays` object, nullable: Extra adults pricing (0=Sunday, 1=Monday, etc.).
    - `childDays` object, nullable: Extra children pricing (0=Sunday, 1=Monday, etc.).
    - `cutOff` integer, nullable: Cut-off: minimum number of days in advance a booking must be made. 0 = no restriction.
    - `lastMinuteBooking` integer, nullable: Last-minute booking: maximum number of days before arrival a booking may be made. 0 = no restriction.
    - `closedToArrival` boolean, nullable: Closed to arrival: when true, guests cannot start a stay on dates within this interval.
    - `closedToDeparture` boolean, nullable: Closed to departure: when true, guests cannot end a stay on dates within this interval.
    - `limitToNumberOfRooms` integer, nullable: Saleable Accommodations: caps how many rooms of the room type this rate may sell. Null, absent or 0 means no limit — the rate may sell the room type's full capacity. A value above the room type's capacity is accepted and stored as sent.
  - `addons` RatePlanAddonRequestSchema[], nullable: List of addons.
    - `addonId` string, required: The addon ID.
    - `settings` 'package_inclusive' | 'show_as_combined' | 'show_as_separate', required: The addon settings.
  - `segmentId` integer, nullable: Segment ID associated with the rate plan.
  - `policyId` integer, nullable: Policy ID associated with the rate plan.

## Response `201`

Created Rate Plan.

- RatePlanResponseSchema
  - `id` string
  - `propertyId` string, nullable
  - `isActive` boolean
  - `status` 'active' | 'expired' | 'no-intervals' | 'disabled': Derived from isActive and the intervals' end dates, using the property's current date. `disabled`: isActive is false. `no-intervals`: active with no intervals. `expired`: active and every interval's endDate is in the past. `active`: active with at least one interval whose endDate is today or later (or has no endDate).
  - `isDeleted` boolean
  - `derivedRatePlanId` string, nullable
  - `isDerived` boolean
  - `derivedType` string, nullable
  - `derivedValue` number, float, nullable
  - `addons` RatePlanAddonResponseSchema[], nullable
    - `id` string, nullable, required
    - `addonId` string, nullable, required
    - `settings` 'package_inclusive' | 'show_as_combined' | 'show_as_separate', nullable, required: The addon settings.
  - `promoCode` string, nullable
  - `sources` string[], nullable
  - `name` object, nullable
  - `description` object, nullable
  - `namePrivate` object, nullable
  - `terms` object, nullable
  - `intervals` RatePlanIntervalResponseSchema[], nullable
    - `name` string, nullable
    - `ratePlanId` integer, nullable, required
    - `roomTypeId` integer, nullable, required
    - `startDate` string, date-time, nullable, required
    - `endDate` string, date-time, nullable, required
    - `minLos` integer, nullable
    - `maxLos` integer, nullable
    - `days` number[], nullable, required: Base price per day-of-week, indexed 0=Sunday … 6=Saturday. A day with no base price is null.
    - `adultDays` object, nullable: Extra adults pricing. Outer key = day-of-week (0=Sunday … 6=Saturday); inner key = extra-guest count; value = additional price for that guest. Note: when fees are set on a contiguous run of days starting at day 0 (e.g. all 7 days), the payload serializes as a JSON array of per-day objects rather than the day-of-week-keyed object shown here.
    - `childDays` object, nullable: Extra children pricing. Outer key = day-of-week (0=Sunday … 6=Saturday); inner key = extra-guest count; value = additional price for that guest. Note: when fees are set on a contiguous run of days starting at day 0 (e.g. all 7 days), the payload serializes as a JSON array of per-day objects rather than the day-of-week-keyed object shown here.
    - `cutOff` integer, nullable: Cut-off: minimum number of days in advance a booking must be made. 0 = no restriction.
    - `lastMinuteBooking` integer, nullable: Last-minute booking: maximum number of days before arrival a booking may be made. 0 = no restriction.
    - `closedToArrival` boolean, nullable: Closed to arrival: when true, guests cannot start a stay on dates within this interval.
    - `closedToDeparture` boolean, nullable: Closed to departure: when true, guests cannot end a stay on dates within this interval.
    - `limitToNumberOfRooms` integer, nullable: Saleable Accommodations: caps how many rooms of the room type this rate may sell. Null means no limit — the rate may sell the room type's full capacity.
    - `agePolicyPricing` object[], nullable: Age-group pricing for this interval, one entry per priced age group — or, under per_each_guest pricing, one entry per extra-guest position within a group, so several entries can share an ageGroupId and differ by guestNumber. Null when the property does not use age-group pricing, or when this interval's rate still prices guests with the adultDays / childDays model — in which case those two fields carry the pricing. An empty array means age-group pricing applies to this interval but nothing is priced on it yet. Join ageGroupId against GET /age-policy/v1/policies for each group's name and age range.
      - `ageGroupId` integer, required: Age group this price applies to.
      - `isExtraGuestsPricing` boolean, required: True when the price applies to a guest beyond base occupancy rather than to the base rate.
      - `extraGuestsType` 'per_age_group' | 'per_each_guest', nullable: The property's extra-guest pricing mode: per_age_group prices every extra guest of a group alike, per_each_guest prices each position separately.
      - `guestNumber` integer, nullable: Extra-guest position this price applies to, counting from the first guest beyond base occupancy. Only set under per_each_guest pricing.
      - `days` object[], required: Price per day-of-week. A day with no price is absent from the list.
        - `dayOfWeek` integer, required: 0=Sunday … 6=Saturday.
        - `priceAmount` string, required: Decimal amount, with at least two decimal places and up to four — a price finer than cents keeps the decimals it needs, so do not parse this as a fixed-width two-decimal string.
        - `priceCurrency` string, required: ISO 4217 currency code.
  - `createdAt` string, date-time, nullable
  - `updatedAt` string, date-time, nullable
  - `policyId` string, nullable
  - `segmentId` string, nullable
  - `mealPlans` string[], required: Meal plans carried by the add-ons listed in `addons` (any attachment setting), as raw keys (not localized labels), deduplicated. Empty when none of them is a meal plan.

## Other responses

- `400`: Bad request response.
- `403`: Forbidden response.
- `404`: Not found response.
- `500`: Internal server error.

---

[API](https://skmtc.dev/cloudbeds/apis/cloudbeds-api-v2.md) - [All operations](https://skmtc.dev/cloudbeds/apis/cloudbeds-api-v2/llms.txt) - [OpenAPI document](https://skmtc.dev/cloudbeds/apis/cloudbeds-api-v2/revisions/69bffac143cc?raw)