Beyond Pricing Customizations API

openapi: 3.2.0
info:
  title: Beyond Pricing Public Customizations API
  version: 2.0.0
  description: Bearer-protected API for third-party integrations. Supports OAuth2 client credentials and personal access tokens. Follows JSON:API specification.
tags:
- name: Customizations
paths:
  /api/v1/listings/{listing_id}/customizations/:
    get:
      operationId: get_listing_all_customizations
      description: Retrieve every supported customization for a listing.
      summary: Get all customizations for a listing
      parameters:
      - in: path
        name: listing_id
        schema:
          type: integer
        required: true
      - in: query
        name: fields[listing-customizations]
        schema:
          type: array
          items:
            type: string
            enum:
            - base-price
            - extra-guest-fees
            - min-max-prices
            - min-stays
            - time-based-adjustments
            - id
        description: endpoint return only specific fields in the response on a per-type basis by including a fields[TYPE] query parameter.
        explode: false
      tags:
      - Customizations
      security:
      - oauth2:
        - listings:read
      - personalAccessToken: []
      responses:
        '200':
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ListingCustomizationsResponse'
          description: ''
        '401':
          description: Unauthorized - invalid or missing bearer token
        '403':
          description: Forbidden
        '404':
          description: Not found - resource does not exist
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
  /api/v1/listings/{listing_id}/customizations/base-price/:
    get:
      operationId: get_listing_base_price_customization
      description: Retrieve base price customization for a listing.
      summary: Get base price customization for a listing
      parameters:
      - in: path
        name: listing_id
        schema:
          type: integer
        required: true
      - in: query
        name: fields[base-price-customizations]
        schema:
          type: array
          items:
            type: string
            enum:
            - base-price
            - id
        description: endpoint return only specific fields in the response on a per-type basis by including a fields[TYPE] query parameter.
        explode: false
      tags:
      - Customizations
      security:
      - oauth2:
        - listings:read
      - personalAccessToken: []
      responses:
        '200':
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/BasePriceCustomizationResponse'
          description: ''
        '401':
          description: Unauthorized - invalid or missing bearer token
        '403':
          description: Forbidden
        '404':
          description: Not found - resource does not exist
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
    patch:
      operationId: patch_listing_base_price_customization
      description: Update base price customization for a listing.
      summary: Update base price customization for a listing
      parameters:
      - in: path
        name: listing_id
        schema:
          type: integer
        required: true
      tags:
      - Customizations
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/PatchedBasePriceCustomizationRequest'
        required: true
      security:
      - oauth2:
        - listings:write
      - personalAccessToken: []
      responses:
        '200':
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/BasePriceCustomizationResponse'
          description: ''
        '400':
          description: Validation error
        '401':
          description: Unauthorized - invalid or missing bearer token
        '403':
          description: Forbidden
        '404':
          description: Not found - resource does not exist
        '422':
          description: Unprocessable entity
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
  /api/v1/listings/{listing_id}/customizations/extra-guest-fees/:
    get:
      operationId: get_listing_extra_guest_fee_customization
      description: Retrieve extra guest fee customization for a listing.
      summary: Get extra guest fee customization for a listing
      parameters:
      - in: path
        name: listing_id
        schema:
          type: integer
        required: true
      - in: query
        name: fields[extra-guest-fee-customizations]
        schema:
          type: array
          items:
            type: string
            enum:
            - extra-guest-fee
            - extra-guest-threshold
            - id
        description: endpoint return only specific fields in the response on a per-type basis by including a fields[TYPE] query parameter.
        explode: false
      tags:
      - Customizations
      security:
      - oauth2:
        - listings:read
      - personalAccessToken: []
      responses:
        '200':
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ExtraGuestFeeCustomizationResponse'
          description: ''
        '401':
          description: Unauthorized - invalid or missing bearer token
        '403':
          description: Forbidden
        '404':
          description: Not found - resource does not exist
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
    patch:
      operationId: patch_listing_extra_guest_fee_customization
      description: Update extra guest fee customization for a listing.
      summary: Update extra guest fee customization for a listing
      parameters:
      - in: path
        name: listing_id
        schema:
          type: integer
        required: true
      tags:
      - Customizations
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/PatchedExtraGuestFeeCustomizationRequest'
        required: true
      security:
      - oauth2:
        - listings:write
      - personalAccessToken: []
      responses:
        '200':
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ExtraGuestFeeCustomizationResponse'
          description: ''
        '400':
          description: Validation error
        '401':
          description: Unauthorized - invalid or missing bearer token
        '403':
          description: Forbidden
        '404':
          description: Not found - resource does not exist
        '422':
          description: Unprocessable entity
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
  /api/v1/listings/{listing_id}/customizations/min-max-prices/:
    get:
      operationId: get_listing_min_max_prices_customization
      description: Retrieve min/max prices customization for a listing.
      summary: Get min/max prices customization for a listing
      parameters:
      - in: path
        name: listing_id
        schema:
          type: integer
        required: true
      - in: query
        name: fields[min-max-price-customizations]
        schema:
          type: array
          items:
            type: string
            enum:
            - min-price
            - max-price
            - monthly-min-price
            - day-of-week-min-prices
            - seasonal-day-of-week-min-prices
            - seasonal-prices
            - seasonal-monthly-prices
            - id
        description: endpoint return only specific fields in the response on a per-type basis by including a fields[TYPE] query parameter.
        explode: false
      tags:
      - Customizations
      security:
      - oauth2:
        - listings:read
      - personalAccessToken: []
      responses:
        '200':
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/MinMaxPricesCustomizationResponse'
          description: ''
        '401':
          description: Unauthorized - invalid or missing bearer token
        '403':
          description: Forbidden
        '404':
          description: Not found - resource does not exist
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
    patch:
      operationId: patch_listing_min_max_prices_customization
      description: Update min/max prices customization for a listing.
      summary: Update min/max prices customization for a listing
      parameters:
      - in: path
        name: listing_id
        schema:
          type: integer
        required: true
      tags:
      - Customizations
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/PatchedMinMaxPricesCustomizationRequest'
        required: true
      security:
      - oauth2:
        - listings:write
      - personalAccessToken: []
      responses:
        '200':
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/MinMaxPricesCustomizationResponse'
          description: ''
        '400':
          description: Validation error
        '401':
          description: Unauthorized - invalid or missing bearer token
        '403':
          description: Forbidden
        '404':
          description: Not found - resource does not exist
        '422':
          description: Unprocessable entity
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
  /api/v1/listings/{listing_id}/customizations/min-stays/:
    get:
      operationId: get_listing_min_stays_customization
      description: Retrieve min-stays customization for a listing.
      summary: Get min-stays customization for a listing
      parameters:
      - in: path
        name: listing_id
        schema:
          type: integer
        required: true
      - in: query
        name: fields[min-stay-customizations]
        schema:
          type: array
          items:
            type: string
            enum:
            - min-stay
            - gap-fill-min-stay
            - seasonal-min-stays
            - last-minute-min-stays
            - day-of-week-min-stays
            - seasonal-day-of-week-min-stays
            - seasonal-gap-fill-min-stays
            - seasonal-time-based-min-stays
            - id
        description: endpoint return only specific fields in the response on a per-type basis by including a fields[TYPE] query parameter.
        explode: false
      tags:
      - Customizations
      security:
      - oauth2:
        - listings:read
      - personalAccessToken: []
      responses:
        '200':
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/MinStaysCustomizationResponse'
          description: ''
        '401':
          description: Unauthorized - invalid or missing bearer token
        '403':
          description: Forbidden
        '404':
          description: Not found - resource does not exist
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
    patch:
      operationId: patch_listing_min_stays_customization
      description: Update min-stays customization for a listing.
      summary: Update min-stays customization for a listing
      parameters:
      - in: path
        name: listing_id
        schema:
          type: integer
        required: true
      tags:
      - Customizations
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/PatchedMinStaysCustomizationRequest'
        required: true
      security:
      - oauth2:
        - listings:write
      - personalAccessToken: []
      responses:
        '200':
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/MinStaysCustomizationResponse'
          description: ''
        '400':
          description: Validation error
        '401':
          description: Unauthorized - invalid or missing bearer token
        '403':
          description: Forbidden
        '404':
          description: Not found - resource does not exist
        '422':
          description: Unprocessable entity
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
  /api/v1/listings/{listing_id}/customizations/time-based-adjustments/:
    get:
      operationId: get_listing_time_based_adjustments_customization
      description: Retrieve time-based adjustments customization for a listing.
      summary: Get time-based adjustments customization for a listing
      parameters:
      - in: path
        name: listing_id
        schema:
          type: integer
        required: true
      - in: query
        name: fields[time-based-adjustment-customizations]
        schema:
          type: array
          items:
            type: string
            enum:
            - time-based-adjustments
            - seasonal-time-based-adjustments
            - id
            - dynamic-time-based-adjustments
        description: endpoint return only specific fields in the response on a per-type basis by including a fields[TYPE] query parameter.
        explode: false
      tags:
      - Customizations
      security:
      - oauth2:
        - listings:read
      - personalAccessToken: []
      responses:
        '200':
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/TimeBasedAdjustmentsCustomizationResponse'
          description: ''
        '401':
          description: Unauthorized - invalid or missing bearer token
        '403':
          description: Forbidden
        '404':
          description: Not found - resource does not exist
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
    patch:
      operationId: patch_listing_time_based_adjustments_customization
      description: Update time-based adjustments customization for a listing.
      summary: Update time-based adjustments customization for a listing
      parameters:
      - in: path
        name: listing_id
        schema:
          type: integer
        required: true
      tags:
      - Customizations
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/PatchedTimeBasedAdjustmentsCustomizationRequest'
        required: true
      security:
      - oauth2:
        - listings:write
      - personalAccessToken: []
      responses:
        '200':
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/TimeBasedAdjustmentsCustomizationResponse'
          description: ''
        '400':
          description: Validation error
        '401':
          description: Unauthorized - invalid or missing bearer token
        '403':
          description: Forbidden
        '404':
          description: Not found - resource does not exist
        '422':
          description: Unprocessable entity
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
components:
  schemas:
    MinMaxPricesCustomizationNested:
      type: object
      description: Min/max prices customization nested in the aggregate response.
      properties:
        min-price:
          type:
          - number
          - 'null'
          format: double
          minimum: 5
          description: Default minimum nightly price for the listing.
        max-price:
          type:
          - number
          - 'null'
          format: double
          description: Default maximum nightly price for the listing.
        monthly-min-price:
          type:
          - number
          - 'null'
          format: double
          minimum: 5
          description: Default minimum monthly price for the listing.
        day-of-week-min-prices:
          type: array
          items:
            $ref: '#/components/schemas/DayOfWeekMinPrice'
          description: Year-round minimum nightly prices keyed by weekday.
        seasonal-day-of-week-min-prices:
          type: array
          items:
            $ref: '#/components/schemas/SeasonalDayOfWeekMinPrice'
          description: Weekday-specific nightly min prices limited to seasonal ranges.
        seasonal-prices:
          type: array
          items:
            $ref: '#/components/schemas/SeasonalPrices'
          description: Seasonal nightly min/max price overrides.
        seasonal-monthly-prices:
          type: array
          items:
            $ref: '#/components/schemas/SeasonalMonthlyPrices'
          description: Seasonal monthly min/max price overrides.
    SeasonalMinStayRequest:
      type: object
      description: A date-scoped minimum-stay override.
      properties:
        start-date:
          type: string
          format: date
          description: First date the seasonal rule applies.
        end-date:
          type: string
          format: date
          description: Last date the seasonal rule applies.
        rollover:
          type: boolean
          default: false
          description: Whether the seasonal rule repeats across the year boundary.
        min-stay:
          type: integer
          minimum: 1
          description: Minimum required stay, in nights, for the seasonal range.
        min-stay-locked:
          type: boolean
          default: false
          description: Whether this seasonal min stay is locked against automatic changes.
      required:
      - end-date
      - min-stay
      - start-date
    ExtraGuestFeeCustomizationNested:
      type: object
      description: Extra guest fee customization nested in the aggregate response.
      properties:
        extra-guest-fee:
          type:
          - integer
          - 'null'
          minimum: 1
          description: Per-guest fee charged once the booking exceeds the extra guest threshold.
        extra-guest-threshold:
          type:
          - integer
          - 'null'
          minimum: 1
          description: Number of guests included before the extra guest fee applies.
      required:
      - extra-guest-fee
      - extra-guest-threshold
    MinStaysCustomizationResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/MinStaysCustomization'
      required:
      - data
    SeasonalTimeBasedMinStay:
      type: object
      description: Lead-time min-stay rules limited to a seasonal date range.
      properties:
        start-date:
          type: string
          format: date
          description: First date the seasonal rule applies.
        end-date:
          type: string
          format: date
          description: Last date the seasonal rule applies.
        exclude:
          type: boolean
          default: false
          description: Whether this range excludes seasonal lead-time min-stay rules.
        time-based-min-stays:
          type: array
          items:
            $ref: '#/components/schemas/TimeBasedMinStay'
          description: Lead-time min-stay rules that apply only within the seasonal range.
      required:
      - end-date
      - start-date
    PatchedExtraGuestFeeCustomizationRequest:
      type: object
      properties:
        data:
          type: object
          required:
          - type
          - id
          additionalProperties: false
          properties:
            type:
              type: string
              description: The [type](https://jsonapi.org/format/#document-resource-object-identification) member is used to describe resource objects that share common attributes and relationships.
              enum:
              - extra-guest-fee-customizations
            id: {}
            attributes:
              type: object
              properties:
                extra-guest-fee:
                  type:
                  - integer
                  - 'null'
                  minimum: 1
                  description: Per-guest fee charged once the booking exceeds the extra guest threshold.
                extra-guest-threshold:
                  type:
                  - integer
                  - 'null'
                  minimum: 1
                  description: Number of guests included before the extra guest fee applies.
                id:
                  type: string
                  readOnly: true
                  minLength: 1
                  description: Customization resource identifier, returned as the listing ID.
              required:
              - extra-guest-fee
              - extra-guest-threshold
      required:
      - data
    SeasonalPricesRequest:
      type: object
      description: A date-scoped nightly min/max price override.
      properties:
        start-date:
          type: string
          format: date
          description: First date the seasonal rule applies.
        end-date:
          type: string
          format: date
          description: Last date the seasonal rule applies.
        rollover:
          type: boolean
          default: false
          description: Whether the seasonal rule repeats across the year boundary.
        min-price:
          type:
          - number
          - 'null'
          format: double
          minimum: 5
          description: Minimum nightly price for the seasonal range.
        max-price:
          type:
          - number
          - 'null'
          format: double
          description: Maximum nightly price for the seasonal range.
      required:
      - end-date
      - start-date
    SeasonalGapFillMinStayRequest:
      type: object
      description: Gap-fill min-stay settings limited to a seasonal date range.
      properties:
        start-date:
          type: string
          format: date
          description: First date the seasonal rule applies.
        end-date:
          type: string
          format: date
          description: Last date the seasonal rule applies.
        gap-fill-min-stay:
          allOf:
          - $ref: '#/components/schemas/GapFillMinStayRequest'
          description: Gap-fill settings to apply within the seasonal range.
      required:
      - end-date
      - gap-fill-min-stay
      - start-date
    SeasonalMonthlyPricesRequest:
      type: object
      description: A date-scoped monthly min/max price override.
      properties:
        start-date:
          type: string
          format: date
          description: First date the seasonal rule applies.
        end-date:
          type: string
          format: date
          description: Last date the seasonal rule applies.
        rollover:
          type: boolean
          default: false
          description: Whether the seasonal rule repeats across the year boundary.
        monthly-min-price:
          type:
          - number
          - 'null'
          format: double
          minimum: 5
          description: Minimum monthly price for the seasonal range.
        monthly-max-price:
          type:
          - number
          - 'null'
          format: double
          description: Maximum monthly price for the seasonal range.
      required:
      - end-date
      - start-date
    TimeBasedAdjustmentCustomizationResourceTypeEnum:
      type: string
      enum:
      - time-based-adjustment-customizations
    BasePriceCustomizationTypeEnum:
      type: string
      enum:
      - base-price-customizations
    TierEnum:
      enum:
      - revenue
      - occupancy
      - rate
      type: string
      description: '* `revenue` - revenue

        * `occupancy` - occupancy

        * `rate` - rate'
    DayOfWeekMinStay:
      type: object
      description: A minimum-stay override for a specific weekday.
      properties:
        weekday:
          allOf:
          - $ref: '#/components/schemas/WeekdayEnum'
          description: 'Day of week this override applies to.


            * `monday` - monday

            * `tuesday` - tuesday

            * `wednesday` - wednesday

            * `thursday` - thursday

            * `friday` - friday

            * `saturday` - saturday

            * `sunday` - sunday'
        min-stay:
          type:
          - integer
          - 'null'
          minimum: 1
          description: Minimum stay, in nights, to require on that weekday.
      required:
      - weekday
    SeasonalTimeBasedMinStayRequest:
      type: object
      description: Lead-time min-stay rules limited to a seasonal date range.
      properties:
        start-date:
          type: string
          format: date
          description: First date the seasonal rule applies.
        end-date:
          type: string
          format: date
          description: Last date the seasonal rule applies.
        exclude:
          type: boolean
          default: false
          description: Whether this range excludes seasonal lead-time min-stay rules.
        time-based-min-stays:
          type: array
          items:
            $ref: '#/components/schemas/TimeBasedMinStayRequest'
          description: Lead-time min-stay rules that apply only within the seasonal range.
      required:
      - end-date
      - start-date
    DayOfWeekMinPriceRequest:
      type: object
      description: A nightly minimum-price override for a specific weekday.
      properties:
        weekday:
          allOf:
          - $ref: '#/components/schemas/WeekdayEnum'
          description: 'Day of week this override applies to.


            * `monday` - monday

            * `tuesday` - tuesday

            * `wednesday` - wednesday

            * `thursday` - thursday

            * `friday` - friday

            * `saturday` - saturday

            * `sunday` - sunday'
        min-price:
          type:
          - integer
          - 'null'
          minimum: 5
          description: Minimum nightly price to use on that weekday.
      required:
      - weekday
    TimeBasedMinStayRequest:
      type: object
      description: A lead-time-based minimum-stay rule.
      properties:
        days-away:
          type: integer
          minimum: 1
          description: Lead-time threshold, in days, that triggers the rule.
        direction:
          allOf:
          - $ref: '#/components/schemas/DirectionEnum'
          description: 'How to count the lead-time threshold: `within` for bookings within N days, `after` for bookings N or more days away.


            * `within` - within

            * `after` - after'
        min-stay:
          type: integer
          minimum: 1
          description: Minimum stay, in nights, to require when the rule matches.
      required:
      - days-away
      - direction
      - min-stay
    BasePriceCustomizationNested:
      type: object
      description: Base price customization nested in the aggregate response.
      properties:
        base-price:
          type: integer
          minimum: 10
          description: Default nightly base price for the listing. Must be at least 10.
      required:
      - base-price
    MinStayCustomizationResourceTypeEnum:
      type: string
      enum:
      - min-stay-customizations
    SeasonalDayOfWeekMinPrice:
      type: object
      description: Weekday-specific nightly minimum prices limited to a date range.
      properties:
        start-date:
          type: string
          format: date
          description: First date the seasonal rule applies.
        end-date:
          type: string
          format: date
          description: Last date the seasonal rule applies.
        min-prices:
          type: array
          items:
            $ref: '#/components/schemas/DayOfWeekMinPrice'
          description: Seven weekday entries describing the min price for each day.
      required:
      - end-date
      - min-prices
      - start-date
    ExtraGuestFeeCustomizationResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ExtraGuestFeeCustomization'
      required:
      - data
    ListingCustomizationResourceTypeEnum:
      type: string
      enum:
      - listing-customizations
    PatchedBasePriceCustomizationRequest:
      type: object
      properties:
        data:
          type: object
          required:
          - type
          - id
          additionalProperties: false
          properties:
            type:
              type: string
              description: The [type](https://jsonapi.org/format/#document-resource-object-identification) member is used to describe resource objects that share common attributes and relationships.
              enum:
              - base-price-customizations
            id: {}
            attributes:
              type: object
              properties:
                base-price:
                  type: integer
                  minimum: 10
                  description: Default nightly base price for the listing. Must be at least 10.
                id:
                  type: string
                  readOnly: true
                  minLength: 1
                  description: Customization resource identifier, returned as the listing ID.
              required:
              - base-price
      required:
      - data
    SeasonalDayOfWeekMinStayRequest:
      type: object
      description: Weekday-specific minimum stays limited to a date range.
      properties:
        start-date:
          type: string
          format: date
          description: First date the seasonal rule applies.
        end-date:
          type: string
          format: date
          description: Last date the seasonal rule applies.
        min-stays:
          type: array
          items:
            $ref: '#/components/schemas/DayOfWeekMinStayRequest'
          description: Seven weekday entries describing the min stay for each day.
      required:
      - end-date
      - min-stays
      - start-date
    SeasonalMinStay:
      type: object
      description: A date-scoped minimum-stay override.
      properties:
        start-date:
          type: string
          format: date
          description: First date the seasonal rule applies.
        end-date:
          type: string
          format: date
          description: Last date the seasonal rule applies.
        rollover:
          type: boolean
          default: false
          description: Whether the seasonal rule repeats across the year boundary.
        min-stay:
          type: integer
          minimum: 1
          description: Minimum required stay, in nights, for the seasonal range.
        min-stay-locked:
          type: boolean
          default: false
          description: Whether this seasonal min stay is locked against automatic changes.
      required:
      - end-date
      - min-stay
      - start-date
    SeasonalPrices:
      type: object
      description: A date-scoped nightly min/max price override.
      properties:
        start-date:
          type: string
          format: date
          description: First date the seasonal rule applies.
        end-date:
          type: string
          format: date
          description: Last date the seasonal rule applies.
        rollover:
          type: boolean
          default: false
          description: Whether the seasonal rule repeats across the year boundary.
        min-price:
          type:
          - number
          - 'null'
          format: double
          minimum: 5
          description: Minimum nightly price for the seasonal range.
        max-price:
          type:
          - number
          - 'null'
          format: double
          description: Maximum nightly price for the seasonal range.
      required:
      - end-date
      - start-date
    ExtraGuestFeeCustomizationResourceTypeEnum:
      type: string
      enum:
      - extra-g

# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/beyond-pricing/refs/heads/main/openapi/beyond-pricing-customizations-api-openapi.yml