openapi: 3.0.3
info:
  version: 1.0.0
  title: Value Adds Catalog API
  description: >
    This API provides a list of value adds available for properties. The
    response can be in JSON or XML format depending on the `Accept` header.

    The value adds include dynamic attributes such as currency, amount, and
    more.
  contact:
    name: ''
    url: ''
    email: ''
servers:
  - url: https://supply-xml.booking.com
    description: Test using live endpoint
tags:
  - name: About Try it
    description: >-
      Learn how to effectively use the Try it feature in the Value Adds Catalog
      API documentation.


      Use the **Try it** feature to send test request examples to the API
      endpoints directly from the developer portal and depending on the selected
      environment either see static, pre-built responses or dynamic responses
      from a test property.


      ## Environment


      You can select between two different environments (top right corner in the
      UI):


      **Test static response** (default):

      - Helps to understand the response data schema

      - Recommended for all write operations (POST, PUT, DELETE)

      - Environment for testing without affecting live/test data


      **Test live endpoint**:

      - Make sure to use only test properties.

      - Changes will affect your test property data

      - Requires valid credentials

      - Same API structure as production


      ## Request


      Using the UI, toggle between **Edit** and **Preview** tabs to see the
      values applied to the path or query placeholders (if there are any). You
      can also click on any unresolved placeholders to add a value or edit an
      existing placeholder value.


      The portal loads the default request body. Where the specification
      supports multiple request body examples (for example: Rooms API POST
      endpoint), you can choose a different request body from the drop-down
      list.


      Some helpful pointers before running a request:


      - **Authentication** (when using live endpoint): Configure your
      authentication headers
        - API Key or OAuth token as required. Use the **Environments** tab.
        - Make sure to manage separate machine accounts for test vs. properties in production.
        - Ensure credentials match your selected environment.

      - **Parameters**: Fill in required parameters
        - Path parameters (like `propertyId`)
        - Query parameters (like `language_code`)
        - Request body for `POST/PUT` operations

      - **Execute**: Click **Send** to send the request
        - The request is sent to the selected environment
        - When sending requests to the live endpoint, real HTTP request is made to the API

      ## Response


      The Try it feature provides comprehensive response information to the
      extent supported by the Open API specification:


      ### Status code

      - **2xx**: Success responses (200)

      - **4xx**: Client errors (400 Bad Request, 401 Unauthorized, 404 Not
      Found)

      - **5xx**: Server errors (500 Internal Server Error)


      ### Response body

      - JSON formatted response data


      If the returned response, by default, is unformatted, select the supported
      Response body format in the UI.


      ### Response headers

      - Content-Type, Content-Length.


      ## Environments


      The **Environments** tab allows you to create variables specific to the
      environment. For example, you can add a variable to hold the value of the
      `property-id` placeholder. The portal inserts the respective value
      depending on the environment at the time of sending the request.


      ### Variables


      Most of the endpoints (especially POST/PUT/DELETE) require you to add a
      path or query parameter before sending the request. The Open API
      specification marks these parameters with placeholder tags. For example,
      {{`property_id`}}. You can use the **Environments** tab to manage the
      values for these placeholders as variables.


      #### Path parameters

      - **Required**: Must be provided to make the request

      - **Type validation**: Ensures correct data types (integer, string, etc.)

      - **Example**: No path parameters for this API


      #### Query parameters

      - **Optional**: Usually have default values

      - **Example**: No query parameters for this API


      #### Request body

      - **Schema validation**: Follows OpenAPI schema definitions

      - **Example data**: Prepopulated with sample values


      ## Best practices


      This section provides some basic practice guidelines.


      ### Authentication


      - Always use separate machine accounts for test properties vs. properties
      in production.

      - When testing with production endpoint, make sure to use only test
      properties.


      ### For Read operations (GET)

      - Safe to test in any environment

      - Use valid IDs that exist in your system

      - Check response structure for integration planning


      ### For Write operations (POST, PUT)

      - **Always use static response first**

      - Verify request payload structure

      - Check response for success confirmation

      - Test error scenarios with invalid data


      ### For Delete operations (DELETE)

      - **Use static response environment only**

      - Understand the operation is irreversible

      - Have backup data when testing using test properties


      ## Troubleshooting


      ### Common issues


      **401 Unauthorized**

      - Check authentication credentials

      - Verify API key is valid and not expired

      - Ensure credentials match the selected environment


      **400 Bad Request**

      - Validate request payload against schema

      - Check required fields are provided

      - Verify data types match specification


      **404 Not Found**

      - Confirm the resource ID exists

      - Check the endpoint URL is correct

      - Verify you have access to the resource


      ### Getting help


      If you encounter issues:

      1. Check the response error message for details

      2. Verify your request matches the API specification

      3. Contact the Connectivity Team for support


      ---


      *This documentation applies to all endpoints in the Value Adds Catalog
      API. The Try it feature provides a consistent testing experience across
      all operations.*
  - name: Value Adds
    description: >-
      Retrieve catalog of value adds available for properties with dynamic
      attributes
x-tagGroups:
  - name: API Endpoints
    tags:
      - Value Adds
  - name: Documentation
    tags:
      - About Try it
paths:
  /valueadds/properties/catalog:
    get:
      tags:
        - Value Adds
      summary: Retrieve catalog of value adds for properties
      description: >
        This endpoint returns a list of value adds, including dynamic
        attributes, in either JSON or XML format. The response format is
        determined by the `Accept` header.
      operationId: getValueAddsCatalog
      parameters:
        - name: Accept
          in: header
          description: >
            Specifies the response format. If omitted, JSON is returned by
            default.
          required: false
          schema:
            type: string
            enum:
              - application/json
              - application/xml
      responses:
        '200':
          description: Successful response with a list of value adds.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ValueAdd'
              examples:
                default:
                  value:
                    - id: 2001
                      category: Food and Beverage (F&B)
                      type: Credit or discount
                      name: Daily Credit Per adult - No Daily Accrual
                      attributes:
                        - name: CurrencyCode
                          dataType: string
                          description: Specifies the currency code for the selected amount.
                          required: false
                        - name: Amount
                          dataType: double
                          description: >-
                            Specifies an estimated worth of the value add
                            included in the rate.
                          required: true
            application/xml:
              schema:
                type: object
                properties:
                  valueAdds:
                    type: array
                    items:
                      $ref: '#/components/schemas/ValueAddXML'
              examples:
                default:
                  value:
                    valueAdds:
                      - valueAdd:
                          id: 2001
                          category: Food and Beverage (F&B)
                          type: Credit or discount
                          name: Daily Credit Per adult - No Daily Accrual
                          attributes:
                            - attribute:
                                name: CurrencyCode
                                dataType: string
                                description: >-
                                  Specifies the currency code for the selected
                                  amount.
                                required: false
                            - attribute:
                                name: Amount
                                dataType: double
                                description: >-
                                  Specifies an estimated worth of the value add
                                  included in the rate. The `Amount` attribute
                                  is used only for display purposes and to show
                                  the perceived worth of the specific
                                  value-added service or product.
                                required: true
        '406':
          description: >-
            Unsupported media type. The server only supports JSON and XML
            responses.
          content:
            application/json:
              examples:
                default:
                  value:
                    message: >-
                      Unsupported media type. Accept header must be
                      'application/json' or 'application/xml'.
            application/xml:
              examples:
                default:
                  value:
                    error: >-
                      Unsupported media type. Accept header must be
                      'application/json' or 'application/xml'.
        '500':
          description: Internal Server Error
      servers:
        - url: https://supply-xml.booking.com
          description: Production server
components:
  schemas:
    ValueAdd:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the value add.
          example: 2001
        category:
          type: string
          description: Category of the value add (e.g., Food and Beverage, Spa).
          example: Food and Beverage (F&B)
        type:
          type: string
          description: Type of value add, such as Credit or Discount.
          example: Credit or discount
        name:
          type: string
          description: Name of the value add.
          example: Daily Credit Per adult - No Daily Accrual
        attributes:
          type: array
          description: List of dynamic attributes for the value add.
          items:
            $ref: '#/components/schemas/Attribute'
    Attribute:
      type: object
      properties:
        name:
          type: string
          description: Name of the attribute.
          example: CurrencyCode
        dataType:
          type: string
          description: Data type of the attribute (e.g., string, double).
          example: string
        description:
          type: string
          description: Detailed description of the attribute.
          example: Specifies the currency code for the selected amount.
        required:
          type: boolean
          description: Indicates if the attribute is required.
          example: false
    ValueAddXML:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the value add.
          example: 2001
        category:
          type: string
          description: Category of the value add (e.g., Food and Beverage, Spa).
          example: Food and Beverage (F&B)
        type:
          type: string
          description: Type of value add, such as Credit or Discount.
          example: Credit or discount
        name:
          type: string
          description: Name of the value add.
          example: Daily Credit Per adult - No Daily Accrual
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/AttributeXML'
    AttributeXML:
      type: object
      properties:
        name:
          type: string
          description: Name of the attribute.
          example: CurrencyCode
        dataType:
          type: string
          description: Data type of the attribute (e.g., string, double).
          example: string
        description:
          type: string
          description: Detailed description of the attribute.
          example: Specifies the currency code for the selected amount.
        required:
          type: string
          description: Indicates if the attribute is required (true/false).
          example: false
