openapi: 3.1.0
info:
  title: Subscriptions API for TAAP
  description:  Subscriptions API for TAAP allows partners to subscribe to webhook events with core itinerary updates.
  version: v1

tags:
  - name: Subscriptions API for TAAP

servers:
  - url: https://analytics.ean.com/taap/v1

paths:
  /subscriptions:
    post:
      summary: Create a subscription
      tags:
        - Subscriptions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionBodyRequest'
            example:
              event_type: "taap.itinerary.change"
              endpoint: "https://notification.stub.3ptp.com/v1/webhooks/itineraryEvents"
              configuration:
                include_pii: true
      responses:
        '201':
          description: Subscription created
          headers:
            Rate-Limit-Day:
              $ref: "#/components/headers/Rate-Limit-Day"
            Rate-Limit-Day-Remaining:
              $ref: "#/components/headers/Rate-Limit-Day-Remaining"
            Rate-Limit-Day-Reset:
              $ref: "#/components/headers/Rate-Limit-Day-Reset"
            Rate-Limit-Minute:
              $ref: "#/components/headers/Rate-Limit-Minute"
            Rate-Limit-Minute-Remaining:
              $ref: "#/components/headers/Rate-Limit-Minute-Remaining"
            Rate-Limit-Minute-Reset:
              $ref: "#/components/headers/Rate-Limit-Minute-Reset"
            Rate-Limit-Reduction-Status:
              $ref: "#/components/headers/Rate-Limit-Reduction-Status"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubscriptionDTO"
              example:
                event_type: "taap.itinerary.change"
                subscription_id: "b79d3925-0ca3-4344-bf5e-293373959698"
                endpoint: "https://notification.stub.3ptp.com/v1/webhooks/itineraryEvents"
                configuration:
                  include_pii: true
                shared_secret: "3ibSs8rUGD2NXbSL7uwGwTHfck2SMDeT"
        "400":
          description: Bad Request
          headers:
            Rate-Limit-Day:
              $ref: "#/components/headers/Rate-Limit-Day"
            Rate-Limit-Day-Remaining:
              $ref: "#/components/headers/Rate-Limit-Day-Remaining"
            Rate-Limit-Day-Reset:
              $ref: "#/components/headers/Rate-Limit-Day-Reset"
            Rate-Limit-Minute:
              $ref: "#/components/headers/Rate-Limit-Minute"
            Rate-Limit-Minute-Remaining:
              $ref: "#/components/headers/Rate-Limit-Minute-Remaining"
            Rate-Limit-Minute-Reset:
              $ref: "#/components/headers/Rate-Limit-Minute-Reset"
            Rate-Limit-Reduction-Status:
              $ref: "#/components/headers/Rate-Limit-Reduction-Status"
          content:
            application/json:
              schema:
                $ref: "./common-models.yaml#/components/schemas/Error"
              examples:
                Error:
                  value:
                    type: BAD_REQUEST
                    message: "An invalid request was sent in, please check the nested errors for details."
                    errors:
                      - type: "endpoint.invalid"
                        message: "Invalid endpoint is specified, expect a https value"
                        fields:
                          - name: endpoint
                            type: body_param
                            value: "{endpoint: \"http://foo\"}"
                      - type: "event_type.invalid"
                        message: "Unknown event_type expected `taap.itinerary.change`"
                        fields:
                          - name: event_type
                            type: body_param
                            value: "{event_type: \"foo.bar.change\"}"
        401:
          $ref: '#/components/responses/Unauthorised'
        403:
          $ref: '#/components/responses/Forbidden'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/InternalServerError'
        503:
          $ref: '#/components/responses/ServiceUnavailable'
    get:
      summary: List all subscriptions
      tags:
        - Subscriptions
      responses:
        '200':
          description: OK
          headers:
            Rate-Limit-Day:
              $ref: "#/components/headers/Rate-Limit-Day"
            Rate-Limit-Day-Remaining:
              $ref: "#/components/headers/Rate-Limit-Day-Remaining"
            Rate-Limit-Day-Reset:
              $ref: "#/components/headers/Rate-Limit-Day-Reset"
            Rate-Limit-Minute:
              $ref: "#/components/headers/Rate-Limit-Minute"
            Rate-Limit-Minute-Remaining:
              $ref: "#/components/headers/Rate-Limit-Minute-Remaining"
            Rate-Limit-Minute-Reset:
              $ref: "#/components/headers/Rate-Limit-Minute-Reset"
            Rate-Limit-Reduction-Status:
              $ref: "#/components/headers/Rate-Limit-Reduction-Status"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SubscriptionDTO"
              example:
                - event_type: "taap.itinerary.change"
                  subscription_id: "b79d3925-0ca3-4344-bf5e-293373959698"
                  endpoint: "https://notification.stub.3ptp.com/v1/webhooks/itineraryEvents"
                  configuration:
                    include_pii: true
        401:
          $ref: '#/components/responses/Unauthorised'
        403:
          $ref: '#/components/responses/Forbidden'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/InternalServerError'
        503:
          $ref: '#/components/responses/ServiceUnavailable'
  /subscriptions/{subscription_id}:
    get:
      operationId: getSubscriptionById
      summary: Get subscription by Id
      tags:
        - Subscriptions
      parameters:
        - $ref: '#/components/parameters/SubscriptionId'
      responses:
        "200":
          description: OK
          headers:
            Rate-Limit-Day:
              $ref: "#/components/headers/Rate-Limit-Day"
            Rate-Limit-Day-Remaining:
              $ref: "#/components/headers/Rate-Limit-Day-Remaining"
            Rate-Limit-Day-Reset:
              $ref: "#/components/headers/Rate-Limit-Day-Reset"
            Rate-Limit-Minute:
              $ref: "#/components/headers/Rate-Limit-Minute"
            Rate-Limit-Minute-Remaining:
              $ref: "#/components/headers/Rate-Limit-Minute-Remaining"
            Rate-Limit-Minute-Reset:
              $ref: "#/components/headers/Rate-Limit-Minute-Reset"
            Rate-Limit-Reduction-Status:
              $ref: "#/components/headers/Rate-Limit-Reduction-Status"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubscriptionDTO"
              example:
                event_type: "taap.itinerary.change"
                subscription_id: "b79d3925-0ca3-4344-bf5e-293373959698"
                endpoint: "https://notification.stub.3ptp.com/v1/webhooks/itineraryEvents"
                configuration:
                  include_pii: true
        "400":
          $ref: '#/components/responses/BadRequest'
        404:
          $ref: '#/components/responses/NotFound'
        401:
          $ref: '#/components/responses/Unauthorised'
        403:
          $ref: '#/components/responses/Forbidden'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/InternalServerError'
        503:
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      operationId: deleteSubscriptionById
      tags:
        - Subscriptions
      summary: Delete a subscription
      parameters:
        - $ref: '#/components/parameters/SubscriptionId'
      responses:
        '204':
          headers:
            Rate-Limit-Day:
              $ref: "#/components/headers/Rate-Limit-Day"
            Rate-Limit-Day-Remaining:
              $ref: "#/components/headers/Rate-Limit-Day-Remaining"
            Rate-Limit-Day-Reset:
              $ref: "#/components/headers/Rate-Limit-Day-Reset"
            Rate-Limit-Minute:
              $ref: "#/components/headers/Rate-Limit-Minute"
            Rate-Limit-Minute-Remaining:
              $ref: "#/components/headers/Rate-Limit-Minute-Remaining"
            Rate-Limit-Minute-Reset:
              $ref: "#/components/headers/Rate-Limit-Minute-Reset"
            Rate-Limit-Reduction-Status:
              $ref: "#/components/headers/Rate-Limit-Reduction-Status"
          description: Subscription deleted
        "400":
          $ref: '#/components/responses/BadRequest'
        404:
          $ref: '#/components/responses/NotFound'
        401:
          $ref: '#/components/responses/Unauthorised'
        403:
          $ref: '#/components/responses/Forbidden'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/InternalServerError'
        503:
          $ref: '#/components/responses/ServiceUnavailable'

components:
  schemas:
    SubscriptionBodyRequest:
      type: object
      required:
        - event_type
        - endpoint
      properties:
        event_type:
          $ref: '#/components/schemas/EventType'
        endpoint:
          type: string
          description: The endpoint to send itinerary updates to
        configuration:
          $ref: '#/components/schemas/SubscriptionConfiguration'
          default:
            include_pii: true
    SubscriptionConfiguration:
      type: object
      properties:
        include_pii:
          type: boolean
          default: true
          description: Whether to include personally identifiable information in the webhook payload
    SubscriptionDTO:
      allOf:
        - $ref: '#/components/schemas/SubscriptionBodyRequest'
        - type: object
          required:
            - subscription_id
          properties:
            subscription_id:
              type: string
              description: The subscription id
            shared_secret:
              type: string
              description: The shared secret to use for the webhook API HMAC

    # Webhook payload and response schemas
    ItineraryReportingEvent:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          example: "1.0"
        type:
          $ref: "#/components/schemas/EventType"
        source:
          type: string
          example: "https://analytics.ean.com/taap/v1"
        id:
          type: string
          format: uuid
          example: "d79d3925-0ca3-4344-bf5e-293373959698"
        time:
          type: string
          format: date-time
          example: "2024-05-17T23:00:00Z"
        datacontenttype:
          type: string
          example: "application/json"
        data:
          $ref: '#/components/schemas/Itinerary'

    EventType:
      type: string
      description: The type of event to subscribe/subscribed to.
      enum:
        - taap.itinerary.change


    Itinerary:
      type: object
      properties:
        itinerary_id:
          type: "string"
          description: The itinerary id
          example: 12345678910111
        status:
          type: "string"
          enum: ["Confirmed", "Cancelled"]
          description: The status of the itinerary one of Confirmed/Cancelled.
          example: Confirmed
        update_date_time:
          type: "string"
          description: The last update date time for the itinerary in ISO-8601 date format (YYYY-MM-dd"T"HH:mm:ss.SSSZ).
          example: 2024-05-17T23:00:00Z
        creation_date:
          type: "string"
          description: The date when the itinerary was created/booked in ISO-8601 date format (YYYY-MM-dd).
          example: 2024-05-16
        online:
          type: "boolean"
          description: Indicates whether the booking made was an online booking or an offline via a support agent.
        point_of_sale_country_code:
          type: "string"
          description: The country code for the point of sale from which customer made the booking
            in two-letter ISO 3166-1 alpha-2 format.
          example: US
        purchaser:
          $ref: "#/components/schemas/Purchaser"
        agency:
          $ref: "#/components/schemas/Agency"
        payment:
          $ref: "#/components/schemas/Payment"
        property_booking_items:
          type: "array"
          items:
            $ref: "#/components/schemas/PropertyBookingItem"
        flight_booking_items:
          type: "array"
          items:
            $ref: "#/components/schemas/FlightBookingItem"
        car_booking_items:
          type: "array"
          items:
            $ref: "#/components/schemas/CarBookingItem"
        activity_booking_items:
          type: "array"
          items:
            $ref: "#/components/schemas/ActivityBookingItem"
        insurance_booking_items:
          type: "array"
          items:
            $ref: "#/components/schemas/InsuranceBookingItem"
        rate:
          $ref: "#/components/schemas/Rate"
          example:
            pricing:
              gross_booking_value:
                billable_currency:
                  currency: USD
                  value: 100.25
              taxes_and_fees:
                billable_currency:
                  currency: USD
                  value: 20.5
        earnings:
          $ref: "#/components/schemas/Earnings"
          example:
            commission:
              billable_currency:
                currency: USD
                value: 9.0
            service_charge:
              amount:
                billable_currency:
                  currency: USD
                  value: 12.5
              taxes_and_fees:
                billable_currency:
                  currency: USD
                  value: 1.0
    Purchaser:
      type: "object"
      properties:
        first_name:
          type: "string"
          description: The first name of the end purchaser of the itinerary, the traveler.
          example: John
        last_name:
          type: "string"
          description: The last name of the end purchaser of the itinerary, the traveler.
          example: Doe
        email:
          type: "string"
          description: The email address of the end customer of the itinerary, the traveler.
          example: john@doe.com
    Agency:
      type: "object"
      properties:
        id:
          type: "string"
          description: Unique identifier of the TAAP Agency.
          example: WS02555
        name:
          type: "string"
          description: The name of the TAAP Agency.
          example: Dorian Grey & Sons Travel
        agent:
          type: object
          properties:
            first_name:
              type: "string"
              description: The first name of the TAAP agent who placed the booking.
              example: Dorian
            last_name:
              type: "string"
              description: The last name of the TAAP agent who placed the booking.
              example: Grey
            email:
              type: "string"
              description: Email of the TAAP agent who placed the booking.
              example: dorian@dgstravel.com
    Payment:
      type: "object"
      properties:
        payment_type:
          type: "string"
          description: The payment type used for the booking.
          example: Credit Card
        status:
          type: "string"
          enum: ["paid", "unpaid"]
          description: The payment status of the booking one of paid/unpaid.
          example: unpaid
        deferred:
          type: "boolean"
          description: Indicates whether the payment was deferred or not.
          example: true
        payment_due_date:
          type: "string"
          description: The payment due date in ISO-8601 date format (YYYY-MM-dd). Only applicable for deferred payments.
          example: 2024-08-10
        payee:
          type: "string"
          description: The entity responsible for making the payment for the itinerary, which could be the customer or agent
          example: customer
    ItemEarnings:
      type: object
      properties:
        commission:
          $ref: "#/components/schemas/CommissionValue"
    Earnings:
      type: object
      properties:
        commission:
          $ref: "#/components/schemas/CommissionValue"
        service_charge:
          $ref: "#/components/schemas/ServiceCharge"

    ServiceCharge:
      type: object
      description: The service charge amount for the booking
      properties:
        amount:
          type: object
          properties:
            billable_currency:
              $ref: "#/components/schemas/BillableAmount"
              example:
                currency: USD
                value: 12.5
        taxes_and_fees:
          $ref: "#/components/schemas/TaxesAndFees"


    PropertyBookingItem:
      type: object
      properties:
        booking_item_id:
          type: "string"
          description: A unique identifier for a single itinerary item in this case a room.
          example: 1400882912
        status:
          type: "string"
          enum: ["Confirmed", "Cancelled"]
          description: The status of the booking item one of Confirmed/Cancelled.
        checkin_date:
          type: "string"
          description: The checkin date at the property in ISO-8601 date format (YYYY-MM-dd).
          example: 2024-10-02
        checkout_date:
          type: "string"
          description: The checkout date at the property in ISO-8601 date format (YYYY-MM-dd).
          example: 2024-10-17
        property:
          $ref: "#/components/schemas/Property"
        room_name:
          type: "string"
          description: The room type booked e.g Double Room, Private Bathroom.
          example: Comfort Double Room, Private Bathroom
        adult_count:
          type: "number"
          description: Number of adults accounted for within the room.
          example: 1
        child_count:
          type: "number"
          description: Number of children accounted for within the room.
          example: 1
        expedia_collect:
          type: "boolean"
          description: Indicates if payment is made at checkout (true) or to the provider (false).
        property_confirmation_id:
          type: "string"
          description: The confirmation id provided by the hotel or vacation rental company.
          example: 1516171819
        rate:
          $ref: "#/components/schemas/PropertyRate"
          example:
            refundable: true
            pricing:
              gross_booking_value:
                billable_currency:
                  currency: USD
                  value: 50.25
              taxes_and_fees:
                billable_currency:
                  currency: USD
                  value: 5.5
        earnings:
          $ref: "#/components/schemas/ItemEarnings"
          example:
            commission:
              billable_currency:
                currency: USD
                value: 5.0
    Property:
      type: object
      properties:
        id:
          type: "string"
          example: 123456
        chain_name:
          type: "string"
          description: Chains represent a parent company associated with the property.
          example: Independent
        brand_name:
          type: "string"
          description: Represents the brand associated with the chain, a chain can have multiple brands.
          example: Savoy Signature
        name:
          type: "string"
          description: Property name
          example: Hotel 1
        city:
          type: "string"
          description: The name of the city where the property is located.
          example: Toronto
        state_province_name:
          type: "string"
          description: The name of the state or province where the property is located.
          example: Ontario
        country_code:
          type: "string"
          description: The country code for the property location in two-letter ISO 3166-1 alpha-2 format.
          example: CA
        star_rating:
          type: "number"
          description: Star rating of the property
          example: 4
    PropertyRate:
      type: object
      properties:
        refundable:
          type: "boolean"
          description: Whether the booking is refundable or not. Only applicable for lodging items.
        pricing:
          $ref: "#/components/schemas/Pricing"
    Rate:
      type: object
      properties:
        pricing:
          $ref: "#/components/schemas/Pricing"

    FlightBookingItem:
      type: object
      properties:
        booking_item_id:
          type: "string"
          description: A unique identifier for a single itinerary item in this case a flight ticket.
          example: 1400882911
        status:
          type: "string"
          enum: ["Confirmed", "Cancelled"]
          description: The status of the booking item one of Confirmed/Cancelled.
          example: Confirmed
        departure_date:
          type: "string"
          description: The departure date in ISO-8601 date format (YYYY-MM-dd).
          example: 2023-10-02
        arrival_date:
          type: "string"
          description: The arrival date in ISO-8601 date format (YYYY-MM-dd).
          example: 2023-10-02
        airline:
          $ref: "#/components/schemas/Airline"
        carrier_pnr:
          type: "string"
          description: Supplier provided Air Passenger Name Record(PNR)
          example: BCDEFG
        trip_type:
          type: "string"
          enum: ["One Way", "Round Trip", "Multiple Destinations"]
          description: The type of trip e.g `One Way`, `Round Trip`, `Multiple Destinations`
          example: One Way
        fare_class:
          type: "string"
          description: The fare class of the ticket e.g Economy, Business
          example: Business Class
        airport_origin_code:
          type: "string"
          description: The airport code for the origin airport in IATA format.
          example: LHR
        airport_destination_code:
          type: "string"
          description: The airport code for the destination airport in IATA format.
          example: YYZ
        airport_origin_location:
          type: "string"
          description: The location of the origin airport.
          example: London, GB (LHR-Heathrow)
        airport_destination_location:
          type: "string"
          description: The location of the destination airport.
          example: Toronto, ON (YYZ-Lester B. Pearson Intl.)
        ticket_number:
          type: "number"
          description: The ticket number for the flight ticket.
          example: 123456789101
        expedia_collect:
          type: "boolean"
          description: Indicates if payment is made at checkout (true) or to the provider (false).
        segment_count:
          type: "number"
          description: The number of segments in the flight ticket.
        rate:
          $ref: "#/components/schemas/Rate"
          example:
            pricing:
              gross_booking_value:
                billable_currency:
                  currency: USD
                  value: 25.25
              taxes_and_fees:
                billable_currency:
                  currency: USD
                  value: 2.5
        earnings:
          $ref: "#/components/schemas/ItemEarnings"
          example:
            commission:
              billable_currency:
                currency: USD
                value: 2.0
    Airline:
      type: object
      properties:
        plating_carrier_name:
          type: "string"
          description: The plating carrier name for the airline ticket.
          example: Air Canada
        plating_carrier_code:
          type: "string"
          description: The plating carrier code for the airline ticket.
          example: AC

    CarBookingItem:
      type: object
      properties:
        booking_item_id:
          type: "string"
          description: A unique identifier for a single itinerary item in this case a car rental.
          example: 1400882910
        status:
          type: "string"
          enum: ["Confirmed", "Cancelled"]
          description: The status of the booking item one of Confirmed/Cancelled.
        pickup_date:
          type: "string"
          description: The pickup date for the car rental in ISO-8601 date format (YYYY-MM-dd).
          example: 2024-10-02
        return_date:
          type: "string"
          description: The return/drop-off date for the car rental in ISO-8601 date format (YYYY-MM-dd).
          example: 2024-10-02
        rental_company:
          $ref: "#/components/schemas/RentalCompany"
        car_type:
          type: "string"
          description: The type of car rented e.g 2/4 Door_Compact, 4 Door_Sedan
          example: 2/4 Door_Compact
        pickup_location:
          type: "string"
          description: The pickup location for the car rental.
          example: Deer Lake, NL (YDF-Deer Lake Regional)
        pickup_country_code:
          type: "string"
          description: The country code for the pickup location in two-letter ISO 3166-1 alpha-2 format.
          example: CA
        return_location:
          type: "string"
          description: The return/drop-off location for the car rental.
          example: Deer Lake, NL (YDF-Deer Lake Regional)
        return_country_code:
          type: "string"
          description: The country code for the return/drop-off location in two-letter ISO 3166-1 alpha-2 format.
          example: CA
        trip_type:
          type: "string"
          enum: ["One Way", "Round Trip", "Multiple Destinations"]
          description: The type of trip e.g., `One Way`, `Round Trip`, `Multiple Destinations`
          example: Round Trip
        rental_company_confirmation_id:
          type: "string"
          description: The confirmation id provided by the car rental.
          example: ABC1234
        expedia_collect:
          type: "boolean"
          description: Indicates if payment is made at checkout (true) or to the provider (false).
        rate:
          $ref: "#/components/schemas/Rate"
          example:
            pricing:
              gross_booking_value:
                billable_currency:
                  currency: USD
                  value: 10.25
              taxes_and_fees:
                billable_currency:
                  currency: USD
                  value: 1.5
        earnings:
          $ref: "#/components/schemas/ItemEarnings"
          example:
            commission:
              billable_currency:
                currency: USD
                value: 1.0
    RentalCompany:
      type: object
      properties:
        name:
          type: "string"
          description: The name of the car rental company.
          example: Hertz

    ActivityBookingItem:
      type: object
      properties:
        booking_item_id:
          type: "string"
          description: A unique identifier for a single itinerary item in this case an activity.
          example: 1400882910
        status:
          type: "string"
          enum: ["Confirmed", "Cancelled"]
          description: The status of the booking item one of Confirmed/Cancelled.
        activity_start_date:
          type: "string"
          description: The start date of the activity in ISO-8601 date format (YYYY-MM-dd).
          example: 2024-10-08
        activity_end_date:
          type: "string"
          description: The end date of the activity in ISO-8601 date format (YYYY-MM-dd).
          example: 2024-10-08
        vendor:
          $ref: "#/components/schemas/ActivityVendor"
        offering_name:
          type: "string"
          description: The offering name of the activity booked.
          example: Passions of Paradise Great Barrier Reef
        expedia_collect:
          type: "boolean"
          description: Indicates if payment is made at checkout (true) or to the provider (false).
        rate:
          $ref: "#/components/schemas/Rate"
          example:
            pricing:
              gross_booking_value:
                billable_currency:
                  currency: USD
                  value: 10.25
              taxes_and_fees:
                billable_currency:
                  currency: USD
                  value: 1.5
        earnings:
          $ref: "#/components/schemas/ItemEarnings"
          example:
            commission:
              billable_currency:
                currency: USD
                value: 1.0
    ActivityVendor:
      type: object
      properties:
        name:
          type: "string"
          description: The name of the vendor providing the activity.
          example: Viator
        city:
          type: "string"
          description: The city where the activity vendor is located.
          example: Deer Lake
        country_code:
          type: "string"
          description: The country code for the activity vendor in two-letter ISO 3166-1 alpha-2 format.
          example: CA

    InsuranceBookingItem:
      type: object
      description: An insurance component/booking item.
      properties:
        booking_item_id:
          type: "string"
          description: A unique identifier for a single itinerary item in this case an insurance.
          example: 1400882610
        status:
          type: "string"
          enum: ["Confirmed", "Cancelled"]
          example: Confirmed
          description: The status of the booking item one of Confirmed/Cancelled.
        rate:
          $ref: "#/components/schemas/Rate"
          example:
            pricing:
              gross_booking_value:
                billable_currency:
                  currency: USD
                  value: 4.25
              taxes_and_fees:
                billable_currency:
                  currency: USD
                  value: 1.5

    CommissionValue:
      type: object
      description: The commission amount of the booking or the booking item. This is part of the gross booking value.
      properties:
        billable_currency:
          $ref: "#/components/schemas/BillableAmount"
    GrossBookingValue:
      type: object
      description: The gross booking value of the booking.
      properties:
        billable_currency:
          $ref: "#/components/schemas/BillableAmount"
          example:
            currency: USD
            value: 100.25
    TaxesAndFees:
      type: object
      description: The taxes and fees associated with the booking.
      properties:
        billable_currency:
          $ref: "#/components/schemas/BillableAmount"
          example:
            currency: USD
            value: 10.5

    Pricing:
      type: object
      properties:
        gross_booking_value:
          $ref: "#/components/schemas/GrossBookingValue"
        taxes_and_fees:
          $ref: "#/components/schemas/TaxesAndFees"

    BillableAmount:
      type: object
      description: An object representing a billable amount which contains the currency and value of that amount.
      properties:
        currency:
          type: string
          description: Currency Code (ISO 4217) for the billable monetary value.
          example: USD
        value:
          type: number
          description: The monetary value
          example: 100.25

  headers:
    WWW-Authenticate:
      description: Provides an example of the Authorization header.
      schema:
        type: string
    Rate-Limit-Day:
      description: Reserved for future use. Optional header for request capacity per day.
      schema:
        type: number
    Rate-Limit-Day-Remaining:
      description: "Optional header for the remaining capacity, as a percentage, for the daily time window."
      schema:
        type: number
    Rate-Limit-Day-Reset:
      description: "Optional header for the timestamp, as the number of milliseconds since the Unix Epoch, when the daily capacity resets."
      schema:
        type: number
    Rate-Limit-Minute:
      description: Reserved for future use. Optional header for request capacity per minute.
      schema:
        type: number
    Rate-Limit-Minute-Remaining:
      description: "Optional header for the remaining capacity, as a percentage, for the per minute time window."
      schema:
        type: number
    Rate-Limit-Minute-Reset:
      description: "Optional header for the timestamp, as the number of milliseconds since the Unix Epoch, when the per minute capacity resets."
      schema:
        type: number
    Rate-Limit-Reduction-Status:
      description: "Optional header that indicates the state (inactive, active) of minute capacity reduction triggered once all daily capacity has been used."
      schema:
        type: string

  responses:
    BadRequest:
      description: Bad Request
      headers:
        Rate-Limit-Day:
          $ref: "#/components/headers/Rate-Limit-Day"
        Rate-Limit-Day-Remaining:
          $ref: "#/components/headers/Rate-Limit-Day-Remaining"
        Rate-Limit-Day-Reset:
          $ref: "#/components/headers/Rate-Limit-Day-Reset"
        Rate-Limit-Minute:
          $ref: "#/components/headers/Rate-Limit-Minute"
        Rate-Limit-Minute-Remaining:
          $ref: "#/components/headers/Rate-Limit-Minute-Remaining"
        Rate-Limit-Minute-Reset:
          $ref: "#/components/headers/Rate-Limit-Minute-Reset"
        Rate-Limit-Reduction-Status:
          $ref: "#/components/headers/Rate-Limit-Reduction-Status"
      content:
        application/json:
          schema:
            $ref: "./common-models.yaml#/components/schemas/Error"
          examples:
            Error:
              value:
                type: BAD_REQUEST
                message: "An invalid request was sent in, please check the nested errors for details."
                errors:
                  - type: "subscription_id.invalid"
                    message: "Invalid subscription id specified, expect a string value"
                    fields:
                      - name: subscription_id
                        type: path_param
                        value: "{subscription_id: \"123foo456bar\"}"
    NotFound:
      headers:
        Rate-Limit-Day:
          $ref: "#/components/headers/Rate-Limit-Day"
        Rate-Limit-Day-Remaining:
          $ref: "#/components/headers/Rate-Limit-Day-Remaining"
        Rate-Limit-Day-Reset:
          $ref: "#/components/headers/Rate-Limit-Day-Reset"
        Rate-Limit-Minute:
          $ref: "#/components/headers/Rate-Limit-Minute"
        Rate-Limit-Minute-Remaining:
          $ref: "#/components/headers/Rate-Limit-Minute-Remaining"
        Rate-Limit-Minute-Reset:
          $ref: "#/components/headers/Rate-Limit-Minute-Reset"
        Rate-Limit-Reduction-Status:
          $ref: "#/components/headers/Rate-Limit-Reduction-Status"
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "./common-models.yaml#/components/schemas/Error"
          examples:
            Error:
              value:
                type: NOT_FOUND
                message: "Requested subscription id was not found in the system.\
                 \ Please check the subscription id and try again"
    Unauthorised:
      headers:
        WWW-Authenticate:
          $ref: "#/components/headers/WWW-Authenticate"
        Rate-Limit-Day:
          $ref: "#/components/headers/Rate-Limit-Day"
        Rate-Limit-Day-Remaining:
          $ref: "#/components/headers/Rate-Limit-Day-Remaining"
        Rate-Limit-Day-Reset:
          $ref: "#/components/headers/Rate-Limit-Day-Reset"
        Rate-Limit-Minute:
          $ref: "#/components/headers/Rate-Limit-Minute"
        Rate-Limit-Minute-Remaining:
          $ref: "#/components/headers/Rate-Limit-Minute-Remaining"
        Rate-Limit-Minute-Reset:
          $ref: "#/components/headers/Rate-Limit-Minute-Reset"
        Rate-Limit-Reduction-Status:
          $ref: "#/components/headers/Rate-Limit-Reduction-Status"
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: "./common-models.yaml#/components/schemas/Error"
          examples:
            Error:
              value:
                type: UNAUTHORIZED
                message: "Data required to authenticate your request is missing or inaccurate."
    Forbidden:
      headers:
        Rate-Limit-Day:
          $ref: "#/components/headers/Rate-Limit-Day"
        Rate-Limit-Day-Remaining:
          $ref: "#/components/headers/Rate-Limit-Day-Remaining"
        Rate-Limit-Day-Reset:
          $ref: "#/components/headers/Rate-Limit-Day-Reset"
        Rate-Limit-Minute:
          $ref: "#/components/headers/Rate-Limit-Minute"
        Rate-Limit-Minute-Remaining:
          $ref: "#/components/headers/Rate-Limit-Minute-Remaining"
        Rate-Limit-Minute-Reset:
          $ref: "#/components/headers/Rate-Limit-Minute-Reset"
        Rate-Limit-Reduction-Status:
          $ref: "#/components/headers/Rate-Limit-Reduction-Status"
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: "./common-models.yaml#/components/schemas/Error"
          examples:
            Error:
              value:
                type: FORBIDDEN
                message: "Insufficient permissions to perform the request."
    TooManyRequests:
      headers:
        Rate-Limit-Day:
          $ref: "#/components/headers/Rate-Limit-Day"
        Rate-Limit-Day-Remaining:
          $ref: "#/components/headers/Rate-Limit-Day-Remaining"
        Rate-Limit-Day-Reset:
          $ref: "#/components/headers/Rate-Limit-Day-Reset"
        Rate-Limit-Minute:
          $ref: "#/components/headers/Rate-Limit-Minute"
        Rate-Limit-Minute-Remaining:
          $ref: "#/components/headers/Rate-Limit-Minute-Remaining"
        Rate-Limit-Minute-Reset:
          $ref: "#/components/headers/Rate-Limit-Minute-Reset"
        Rate-Limit-Reduction-Status:
          $ref: "#/components/headers/Rate-Limit-Reduction-Status"
      description: Too Many Requests
      content:
        application/json:
          schema:
            $ref: "./common-models.yaml#/components/schemas/Error"
          examples:
            Error:
              value:
                type: TOO_MANY_REQUESTS
                message: "Rate limit exceeded. Please try again later."
    InternalServerError:
      headers:
        Rate-Limit-Day:
          $ref: "#/components/headers/Rate-Limit-Day"
        Rate-Limit-Day-Remaining:
          $ref: "#/components/headers/Rate-Limit-Day-Remaining"
        Rate-Limit-Day-Reset:
          $ref: "#/components/headers/Rate-Limit-Day-Reset"
        Rate-Limit-Minute:
          $ref: "#/components/headers/Rate-Limit-Minute"
        Rate-Limit-Minute-Remaining:
          $ref: "#/components/headers/Rate-Limit-Minute-Remaining"
        Rate-Limit-Minute-Reset:
          $ref: "#/components/headers/Rate-Limit-Minute-Reset"
        Rate-Limit-Reduction-Status:
          $ref: "#/components/headers/Rate-Limit-Reduction-Status"
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: "./common-models.yaml#/components/schemas/Error"
          examples:
            Error:
              value:
                type: INTERNAL_SERVER_ERROR
                message: "An unexpected error occurred. Please try again later."
    ServiceUnavailable:
      headers:
        Rate-Limit-Day:
          $ref: "#/components/headers/Rate-Limit-Day"
        Rate-Limit-Day-Remaining:
          $ref: "#/components/headers/Rate-Limit-Day-Remaining"
        Rate-Limit-Day-Reset:
          $ref: "#/components/headers/Rate-Limit-Day-Reset"
        Rate-Limit-Minute:
          $ref: "#/components/headers/Rate-Limit-Minute"
        Rate-Limit-Minute-Remaining:
          $ref: "#/components/headers/Rate-Limit-Minute-Remaining"
        Rate-Limit-Minute-Reset:
          $ref: "#/components/headers/Rate-Limit-Minute-Reset"
        Rate-Limit-Reduction-Status:
          $ref: "#/components/headers/Rate-Limit-Reduction-Status"
      description: Service Unavailable
      content:
        application/json:
          schema:
            $ref: "./common-models.yaml#/components/schemas/Error"
          examples:
            Error:
              value:
                type: SERVICE_UNAVAILABLE
                message: "Service is temporarily unavailable. Please try again later."
    GatewayTimeout:
      headers:
        Rate-Limit-Day:
          $ref: "#/components/headers/Rate-Limit-Day"
        Rate-Limit-Day-Remaining:
          $ref: "#/components/headers/Rate-Limit-Day-Remaining"
        Rate-Limit-Day-Reset:
          $ref: "#/components/headers/Rate-Limit-Day-Reset"
        Rate-Limit-Minute:
          $ref: "#/components/headers/Rate-Limit-Minute"
        Rate-Limit-Minute-Remaining:
          $ref: "#/components/headers/Rate-Limit-Minute-Remaining"
        Rate-Limit-Minute-Reset:
          $ref: "#/components/headers/Rate-Limit-Minute-Reset"
        Rate-Limit-Reduction-Status:
          $ref: "#/components/headers/Rate-Limit-Reduction-Status"
      description: Gateway Timeout
      content:
        application/json:
          schema:
            $ref: "./common-models.yaml#/components/schemas/Error"
          examples:
            Error:
              value:
                type: GATEWAY_TIMEOUT
                message: "Request timed out. Please try again later."

  parameters:

    SubscriptionId:
      name: subscription_id
      in: path
      description: subscription id to retrieve the subscription details
      schema:
        type: string
        format: uuid
      example: "s79d3925-0ca3-4344-bf5e-293373959698"
      required: true

  securitySchemes:
    oauth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://analytics.ean.com/taap/v1/oauth/token
          scopes:
            demand-solutions.analytics-api-taap-prod.read: "Grants read access to the Analytics API for TAAP"
