openapi: 3.0.0
info:
  description: |
    I am MasSubscriptions API. My intention is to provide a set of REST services for handling subscriptions and their 
    related entities.
  version: 3.0.0
  title: MasSubscriptions
servers:
  - description: production
    url: 'https://subscriptions.masstack.com/v3/'
  - description: staging
    url: 'https://subscriptions.sta.masstack.com/v3/'
security:
  - bearerAuth: [ ]

tags:
  - name: AddOns
    description: AddOns resource represents value-added services associated to subscriptions
  - name: Agile TV
    description: Agile TV resource represents an agile tv subscription containing specific agile tv data besides all data applicable to any subscription
  - name: Amazon Prime
    description: Amazon Prime resource represents an amazon prime subscription containing specific amazon prime data besides all data applicable to any subscription
  - name: Broadband
    description: Broadband resource represents a broadband subscription containing specific broadband data besides all data applicable to any subscription
  - name: Bonuses
    description: Bonuses resource represents bonuses associated to subscriptions
  - name: Devices
    description: Devices resource represents devices associated to subscriptions
  - name: Disney
    description: Disney resource represents a Disney subscription containing specific Disney data besides all data applicable to any subscription
  - name: Max
    description: Max resource represents a Max streaming subscription containing specific Max data besides all data applicable to any subscription
  - name: Mobile
    description: Mobile resource represents a mobile line subscription containing specific mobile related data besides all data applicable to any subscription
  - name: Netflix
    description: Netflix resource represents a Netflix subscription containing specific Netflix data besides all data applicable to any subscription
  - name: Orange TV
    description: Orange TV resource represents a Orange TV subscription containing specific Orange TV data besides all data applicable to any subscription
  - name: Promotions
    description: Promotions resource represents promotions associated to subscriptions
  - name: TV
    description: TV resource represents a TV subscription containing specific TV data besides all data applicable to any subscription

paths:
  '/orgs/{org}/bundles':
    get:
      tags:
        - Bundles
      summary: Search subscriptions bundles
      description: Search subscription bundles providing certain search criteria
      operationId: getBundleList
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/OffsetQueryParam'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/AccountIdQueryParam'
        - $ref: '#/components/parameters/LegacyIdQueryParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BundlesSet'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'
  '/orgs/{org}/bundles/{bundleId}':
    get:
      tags:
        - Bundles
      summary: Get bundle
      description: Get subscription bundle basic info
      operationId: getBundle
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/BundleIdPathParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/BundleNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/subscriptions/amazon_prime':
    post:
      tags:
        - Amazon Prime
      summary: Add Amazon Prime subscription to a bundle
      description: Add a new Amazon Prime subscription to a bundle with the provided data
      operationId: createAmazonPrime
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
      requestBody:
        description: Amazon Prime subscription data
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AmazonPrime'
        required: true
      responses:
        '201':
          description: Amazon Prime subscription successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AmazonPrime'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/BundleNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

    get:
      tags:
        - Amazon Prime
      summary: Search Amazon Prime subscriptions
      description: |
        Search Amazon Prime subscriptions matching given criteria, at least one of the query params is required.
      operationId: getAmazonPrimeSubscriptionList
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/OffsetQueryParam'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/LegacyIdQueryParam'
        - $ref: '#/components/parameters/BundleIdQueryParam'
        - $ref: '#/components/parameters/AccountIdQueryParam'
        - $ref: '#/components/parameters/MandatoryQueryParam'
        - $ref: '#/components/parameters/StatusQueryParam'
        - $ref: '#/components/parameters/TypeQueryParam'
        - $ref: '#/components/parameters/ActivationDateQueryParam'
        - $ref: '#/components/parameters/DeactivationDateQueryParam'
        - $ref: '#/components/parameters/CommercialTransactionIdQueryParam'
        - name: provider_service_id
          in: query
          description: Provider service ID the Amazon Prime subscription is linked to.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AmazonPrimeSet'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/subscriptions/broadband':
    get:
      tags:
        - Broadband
      summary: Search Broadband subscriptions
      description: |
        Search Broadband subscriptions matching given criteria, at least one of the query params is required.
      operationId: getBroadbandSubscriptionList
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/OffsetQueryParam'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/LegacyIdQueryParam'
        - name: legacy_bundle_id
          in: query
          description: Legacy bundle id the subscription is linked to.
          required: false
          schema:
            type: integer
          example: 572234234
        - $ref: '#/components/parameters/AccountIdQueryParam'
        - $ref: '#/components/parameters/MandatoryQueryParam'
        - $ref: '#/components/parameters/StatusQueryParam'
        - $ref: '#/components/parameters/TypeQueryParam'
        - $ref: '#/components/parameters/ActivationDateQueryParam'
        - $ref: '#/components/parameters/DeactivationDateQueryParam'
        - $ref: '#/components/parameters/DeviceIdQueryParam'
        - $ref: '#/components/parameters/LegacyDeviceIdQueryParam'
        - $ref: '#/components/parameters/CommercialTransactionIdQueryParam'
        - name: legacy_service_id
          in: query
          description: Legacy service id the Broadband subscription is linked to.
          required: false
          schema:
            type: string
          example: "MYSIM_528310"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BroadbandSet'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/subscriptions/broadband/{subscriptionId}':
    get:
      tags:
        - Broadband
      summary: Get Broadband subscription by ID
      description: Get a Broadband subscription by its unique identifier
      operationId: getBroadbandSubscriptionById
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Broadband'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/SubscriptionNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/subscriptions/max':
    post:
      tags:
        - Max
      summary: Add Max subscription to a bundle
      description: Add a new Max subscription to a bundle with the provided data
      operationId: createMax
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
      requestBody:
        description: Max subscription data
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Max'
        required: true
      responses:
        '201':
          description: Max subscription successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Max'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/BundleNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

    get:
      tags:
        - Max
      summary: Search Max subscriptions
      description: |
        Search Max subscriptions matching given criteria, at least one of the query params is required.
      operationId: getMaxSubscriptionList
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/OffsetQueryParam'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/LegacyIdQueryParam'
        - $ref: '#/components/parameters/BundleIdQueryParam'
        - $ref: '#/components/parameters/AccountIdQueryParam'
        - $ref: '#/components/parameters/MandatoryQueryParam'
        - $ref: '#/components/parameters/StatusQueryParam'
        - $ref: '#/components/parameters/TypeQueryParam'
        - $ref: '#/components/parameters/ActivationDateQueryParam'
        - $ref: '#/components/parameters/DeactivationDateQueryParam'
        - $ref: '#/components/parameters/CommercialTransactionIdQueryParam'
        - name: provider_service_id
          in: query
          description: Provider service ID the Max subscription is linked to.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaxSet'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/subscriptions/orange_tv':
    post:
      tags:
        - Orange TV
      summary: Add Orange TV subscription to a bundle
      description: Add a new Orange TV subscription to a bundle with the provided data
      operationId: createOrangeTv
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
      requestBody:
        description: Orange TV subscription data
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrangeTv'
        required: true
      responses:
        '201':
          description: Orange TV subscription successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrangeTv'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/BundleNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

    get:
      tags:
        - Orange TV
      summary: Search Orange TV subscriptions
      description: |
        Search Orange TV subscriptions matching given criteria, at least one of the query params is required.
      operationId: getOrangeTvSubscriptionList
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/OffsetQueryParam'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/LegacyIdQueryParam'
        - $ref: '#/components/parameters/BundleIdQueryParam'
        - $ref: '#/components/parameters/AccountIdQueryParam'
        - $ref: '#/components/parameters/MandatoryQueryParam'
        - $ref: '#/components/parameters/StatusQueryParam'
        - $ref: '#/components/parameters/TypeQueryParam'
        - $ref: '#/components/parameters/ActivationDateQueryParam'
        - $ref: '#/components/parameters/DeactivationDateQueryParam'
        - $ref: '#/components/parameters/CommercialTransactionIdQueryParam'
        - name: registration_email
          in: query
          description: Registration email the subscription is linked to.
          required: false
          schema:
            type: string
          example: "peter.sellers@monty.com"
        - name: provider_service_id
          in: query
          description: Provider service id the subscription is linked to.
          required: false
          schema:
            type: string
          example: "masmovil003141592"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrangeTvSet'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/subscriptions/agile_tv':
    post:
      tags:
        - Agile TV
      summary: Create an Agile TV
      description: Create a new Agile TV subscription with the provided data
      operationId: createAgileTv
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
      requestBody:
        description: Agile TV subscription data
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgileTv'
        required: true
      responses:
        '201':
          description: Agile TV subscription successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgileTv'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/BundleNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

    get:
      tags:
        - Agile TV
      summary: Search Agile TV subscriptions
      description: |
        Search Agile TV subscriptions matching given criteria, at least one of the query params is required.
      operationId: getAgileTvSubscriptionList
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/OffsetQueryParam'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/LegacyIdQueryParam'
        - $ref: '#/components/parameters/BundleIdQueryParam'
        - $ref: '#/components/parameters/AccountIdQueryParam'
        - $ref: '#/components/parameters/MandatoryQueryParam'
        - $ref: '#/components/parameters/StatusQueryParam'
        - $ref: '#/components/parameters/TypeQueryParam'
        - $ref: '#/components/parameters/ActivationDateQueryParam'
        - $ref: '#/components/parameters/DeactivationDateQueryParam'
        - $ref: '#/components/parameters/CommercialTransactionIdQueryParam'
        - name: provider_service_id
          in: query
          description: Provider service ID the Agile Tv subscription is linked to.
          required: false
          schema:
            type: string
        - name: provider_product_id
          in: query
          description: Provider product ID the Agile Tv subscription is linked to.
          required: false
          schema:
            type: string
        - name: is_primary
          in: query
          description: Whether the Agile Tv subscription is primary.
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgileTvSet'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/subscriptions/disney':
    post:
      tags:
        - Disney
      summary: Add Disney subscription to a bundle
      description: Add a new Disney subscription to a bundle with the provided data
      operationId: createDisney
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
      requestBody:
        description: Disney subscription data.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Disney'
      responses:
        '201':
          description: Disney subscription successfully added.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Disney'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/BundleNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

    get:
      tags:
        - Disney
      summary: Search Disney subscriptions
      description: |
        Search Disney subscriptions matching given criteria, at least one of the query params is required.
      operationId: getDisneySubscriptionList
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/OffsetQueryParam'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/LegacyIdQueryParam'
        - $ref: '#/components/parameters/BundleIdQueryParam'
        - $ref: '#/components/parameters/AccountIdQueryParam'
        - $ref: '#/components/parameters/MandatoryQueryParam'
        - $ref: '#/components/parameters/StatusQueryParam'
        - $ref: '#/components/parameters/TypeQueryParam'
        - $ref: '#/components/parameters/ActivationDateQueryParam'
        - $ref: '#/components/parameters/DeactivationDateQueryParam'
        - $ref: '#/components/parameters/CommercialTransactionIdQueryParam'
        - name: provider_user_id
          in: query
          description: Provider user ID the Disney subscription is linked to.
          required: false
          schema:
            type: string
        - name: provider_service_id
          in: query
          description: Provider service ID the Disney subscription is linked to.
          required: false
          schema:
            type: string
        - name: provider_product_id
          in: query
          description: Provider product ID the Disney subscription is linked to.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisneySet'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/subscriptions/netflix':
    post:
      tags:
        - Netflix
      summary: Add Netflix subscription to a bundle
      description: Add a new Netflix subscription to a bundle with the provided data
      operationId: createNetflix
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
      requestBody:
        description: Netflix subscription data.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Netflix'
      responses:
        '201':
          description: Netflix subscription successfully added.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Netflix'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/BundleNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

    get:
      tags:
        - Netflix
      summary: Search Netflix subscriptions
      description: |
        Search Netflix subscriptions matching given criteria, at least one of the query params is required.
      operationId: getNetflixSubscriptionList
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/OffsetQueryParam'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/LegacyIdQueryParam'
        - $ref: '#/components/parameters/BundleIdQueryParam'
        - $ref: '#/components/parameters/AccountIdQueryParam'
        - $ref: '#/components/parameters/MandatoryQueryParam'
        - $ref: '#/components/parameters/StatusQueryParam'
        - $ref: '#/components/parameters/TypeQueryParam'
        - $ref: '#/components/parameters/ActivationDateQueryParam'
        - $ref: '#/components/parameters/DeactivationDateQueryParam'
        - $ref: '#/components/parameters/CommercialTransactionIdQueryParam'
        - name: provider_service_id
          in: query
          description: Provider service ID the Netflix subscription is linked to.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NetflixSet'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/subscriptions/mobile':
    get:
      tags:
        - Mobile
      summary: Search mobile subscriptions
      description: Search mobile subscriptions matching certain criteria. Specific type data is included.
      operationId: getMobileSubscriptionList
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/OffsetQueryParam'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/LegacyIdQueryParam'
        - $ref: '#/components/parameters/LegacyBundleIdQueryParam'
        - $ref: '#/components/parameters/AccountIdQueryParam'
        - $ref: '#/components/parameters/MandatoryQueryParam'
        - $ref: '#/components/parameters/StatusQueryParam'
        - $ref: '#/components/parameters/TypeQueryParam'
        - $ref: '#/components/parameters/ActivationDateQueryParam'
        - $ref: '#/components/parameters/DeactivationDateQueryParam'
        - $ref: '#/components/parameters/DeviceIdQueryParam'
        - $ref: '#/components/parameters/LegacyDeviceIdQueryParam'
        - $ref: '#/components/parameters/CommercialTransactionIdQueryParam'
        - $ref: '#/components/parameters/MsisdnQueryParam'
        - $ref: '#/components/parameters/ImsiQueryParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MobileSet'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/subscriptions/mobile/{subscriptionId}':
    get:
      tags:
        - Mobile
      summary: Get mobile subscription by ID
      description: Get a mobile subscription by its unique identifier
      operationId: getMobileSubscriptionById
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mobile'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/SubscriptionNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/subscriptions/tv':
    get:
      tags:
        - TV
      summary: Search TV subscriptions
      description: |
        Search TV subscriptions matching given criteria, at least one of the query params is required.
      operationId: getTvSubscriptionList
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/OffsetQueryParam'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/LegacyIdQueryParam'
        - $ref: '#/components/parameters/LegacyBundleIdQueryParam'
        - $ref: '#/components/parameters/AccountIdQueryParam'
        - $ref: '#/components/parameters/MandatoryQueryParam'
        - $ref: '#/components/parameters/StatusQueryParam'
        - $ref: '#/components/parameters/TypeQueryParam'
        - $ref: '#/components/parameters/ActivationDateQueryParam'
        - $ref: '#/components/parameters/DeactivationDateQueryParam'
        - $ref: '#/components/parameters/DeviceIdQueryParam'
        - $ref: '#/components/parameters/LegacyDeviceIdQueryParam'
        - $ref: '#/components/parameters/CommercialTransactionIdQueryParam'
        - name: legacy_service_id
          in: query
          description: Legacy service id the TV subscription is linked to.
          required: false
          schema:
            type: string
          example: "MYSIM_528310"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TvSet'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/subscriptions/tv/{subscriptionId}':
    get:
      tags:
        - TV
      summary: Get TV subscription by ID
      description: Get a TV subscription by its unique identifier
      operationId: getTvSubscriptionById
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tv'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/SubscriptionNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/subscriptions':
    get:
      tags:
        - Subscription
      summary: Search subscriptions
      description: |
        Search subscriptions matching given criteria, at least one of the query params is required.
      operationId: getSubscriptionList
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/OffsetQueryParam'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/LegacyIdQueryParam'
        - $ref: '#/components/parameters/BundleIdQueryParam'
        - $ref: '#/components/parameters/AccountIdQueryParam'
        - $ref: '#/components/parameters/MandatoryQueryParam'
        - $ref: '#/components/parameters/StatusQueryParam'
        - $ref: '#/components/parameters/TypeQueryParam'
        - $ref: '#/components/parameters/ActivationDateQueryParam'
        - $ref: '#/components/parameters/DeactivationDateQueryParam'
        - $ref: '#/components/parameters/DeviceIdQueryParam'
        - $ref: '#/components/parameters/LegacyDeviceIdQueryParam'
        - $ref: '#/components/parameters/CommercialTransactionIdQueryParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionsSet'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/bundles/{bundleId}/subscriptions':
    get:
      tags:
        - Subscription
      summary: Search subscriptions by bundle
      description: Search subscriptions within a specific bundle
      operationId: getBundleSubscriptionList
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/BundleIdPathParam'
        - $ref: '#/components/parameters/OffsetQueryParam'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/LegacyIdQueryParam'
        - $ref: '#/components/parameters/AccountIdQueryParam'
        - $ref: '#/components/parameters/MandatoryQueryParam'
        - $ref: '#/components/parameters/StatusQueryParam'
        - $ref: '#/components/parameters/TypeQueryParam'
        - $ref: '#/components/parameters/ActivationDateQueryParam'
        - $ref: '#/components/parameters/DeactivationDateQueryParam'
        - $ref: '#/components/parameters/DeviceIdQueryParam'
        - $ref: '#/components/parameters/LegacyDeviceIdQueryParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionsSet'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/BundleNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/subscriptions/{subscriptionId}':
    get:
      tags:
        - Subscription
      summary: Get subscription by ID
      description: Get a subscription by its unique identifier
      operationId: getSubscriptionById
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/SubscriptionNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'
    patch:
      tags:
        - Subscription
      summary: Patch subscription
      description: Apply patch operations to a subscription
      operationId: patchSubscription
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OperationsSet'
      responses:
        '200':
          description: Subscription patched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/SubscriptionNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/subscriptions/{subscriptionId}/promotions/{promotionId}':
    get:
      tags:
        - Promotions
      summary: Get subscription promotion
      description: Get info for a specific promotion of subscription
      operationId: getSubscriptionPromotion
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
        - $ref: '#/components/parameters/PromotionIdPathParam'
      responses:
        '200':
          description: Promotion found for the subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Promotion'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/PromotionNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/subscriptions/{subscriptionId}/bonuses/{bonusId}':
    get:
      tags:
        - Bonuses
      summary: Get subscription bonus
      description: Get info for a specific bonus of subscription
      operationId: getSubscriptionBonus
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
        - $ref: '#/components/parameters/BonusIdPathParam'
      responses:
        '200':
          description: Bonus found for the subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bonus'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/BonusNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/subscriptions/{subscriptionId}/devices/{deviceId}':
    get:
      tags:
        - Devices
      summary: Get device by ID
      description: Get info for a specific device of a subscription
      operationId: getDeviceById
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
        - $ref: '#/components/parameters/DeviceIdPathParam'
      responses:
        '200':
          description: Device found for the subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/DeviceNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'
    patch:
      tags:
        - Devices
      summary: Patch device
      description: Apply patch operations to a device
      operationId: patchDeviceById
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
        - $ref: '#/components/parameters/DeviceIdPathParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OperationsSet'
      responses:
        '200':
          description: Device patched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/DeviceNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/subscriptions/{subscriptionId}/devices/{deviceId}/swap':
    post:
      tags:
        - Devices
      summary: Swap device
      description: Accept a device swap request for a subscription device
      operationId: swapDevice
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
        - $ref: '#/components/parameters/DeviceIdPathParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceSwapRequest'
      responses:
        '202':
          description: Device swap request accepted
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/DeviceNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/subscriptions/{subscriptionId}/cancel':
    post:
      tags:
        - Subscription
      summary: Cancel subscription
      description: Cancel an active subscription
      operationId: cancelSubscription
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
      requestBody:
        description: Cancellation request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionCancellationRequest'
        required: true
      responses:
        '202':
          description: Cancellation process started
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/SubscriptionNotFound'
        '409':
          $ref: '#/components/responses/SubscriptionConflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/subscriptions/{subscriptionId}/deactivate':
    post:
      tags:
        - Subscription
      summary: Deactivate subscription
      description: |
        Starts the deactivation process of the subscription.
      operationId: deactivateSubscription
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
      requestBody:
        description: Deactivate subscription data
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionDeactivationRequest'
        required: true
      responses:
        '202':
          description: Deactivation process started
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/SubscriptionNotFound'
        '409':
          $ref: '#/components/responses/SubscriptionConflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/subscriptions/amazon_prime/{subscriptionId}':
    get:
      tags:
        - Amazon Prime
      summary: Get Amazon Prime subscription by ID
      description: Get an Amazon Prime subscription by its unique identifier
      operationId: getAmazonPrimeSubscriptionById
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AmazonPrime'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/SubscriptionNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'
    patch:
      tags:
        - Amazon Prime
      summary: Patch Amazon Prime subscription
      description: Apply patch operations to an Amazon Prime subscription
      operationId: patchAmazonPrime
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OperationsSet'
      responses:
        '200':
          description: Amazon Prime subscription patched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AmazonPrime'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/SubscriptionNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/bundles/{bundleId}/subscriptions/amazon_prime':
    get:
      tags:
        - Amazon Prime
      summary: Search Amazon Prime subscriptions by bundle
      description: Search Amazon Prime subscriptions within a specific bundle
      operationId: getAmazonPrimeSubscriptionListByBundle
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/BundleIdPathParam'
        - $ref: '#/components/parameters/OffsetQueryParam'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/LegacyIdQueryParam'
        - $ref: '#/components/parameters/AccountIdQueryParam'
        - $ref: '#/components/parameters/MandatoryQueryParam'
        - $ref: '#/components/parameters/StatusQueryParam'
        - $ref: '#/components/parameters/TypeQueryParam'
        - $ref: '#/components/parameters/ActivationDateQueryParam'
        - $ref: '#/components/parameters/DeactivationDateQueryParam'
        - $ref: '#/components/parameters/CommercialTransactionIdQueryParam'
        - name: provider_service_id
          in: query
          description: Provider service ID the Amazon Prime subscription is linked to.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AmazonPrimeSet'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/subscriptions/disney/{subscriptionId}':
    get:
      tags:
        - Disney
      summary: Get Disney subscription by ID
      description: Get a Disney subscription by its unique identifier
      operationId: getDisneySubscriptionById
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Disney'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/SubscriptionNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'
    patch:
      tags:
        - Disney
      summary: Patch Disney subscription
      description: Apply patch operations to a Disney subscription
      operationId: patchDisney
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OperationsSet'
      responses:
        '200':
          description: Disney subscription patched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Disney'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/SubscriptionNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/bundles/{bundleId}/subscriptions/disney':
    get:
      tags:
        - Disney
      summary: Search Disney subscriptions by bundle
      description: Search Disney subscriptions within a specific bundle
      operationId: getDisneySubscriptionListByBundle
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/BundleIdPathParam'
        - $ref: '#/components/parameters/OffsetQueryParam'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/LegacyIdQueryParam'
        - $ref: '#/components/parameters/BundleIdQueryParam'
        - $ref: '#/components/parameters/AccountIdQueryParam'
        - $ref: '#/components/parameters/MandatoryQueryParam'
        - $ref: '#/components/parameters/StatusQueryParam'
        - $ref: '#/components/parameters/TypeQueryParam'
        - $ref: '#/components/parameters/ActivationDateQueryParam'
        - $ref: '#/components/parameters/DeactivationDateQueryParam'
        - $ref: '#/components/parameters/CommercialTransactionIdQueryParam'
        - name: provider_user_id
          in: query
          description: Provider user ID the Disney subscription is linked to.
          required: false
          schema:
            type: string
        - name: provider_service_id
          in: query
          description: Provider service ID the Disney subscription is linked to.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisneySet'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/subscriptions/max/{subscriptionId}':
    get:
      tags:
        - Max
      summary: Get Max subscription by ID
      description: Get a Max subscription by its unique identifier
      operationId: getMaxSubscriptionById
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Max'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/SubscriptionNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'
    patch:
      tags:
        - Max
      summary: Patch Max subscription
      description: Apply patch operations to a Max subscription
      operationId: patchMax
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OperationsSet'
      responses:
        '200':
          description: Max subscription patched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Max'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/SubscriptionNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/bundles/{bundleId}/subscriptions/max':
    get:
      tags:
        - Max
      summary: Search Max subscriptions by bundle
      description: Search Max subscriptions within a specific bundle
      operationId: getMaxSubscriptionListByBundle
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/BundleIdPathParam'
        - $ref: '#/components/parameters/OffsetQueryParam'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/LegacyIdQueryParam'
        - $ref: '#/components/parameters/AccountIdQueryParam'
        - $ref: '#/components/parameters/MandatoryQueryParam'
        - $ref: '#/components/parameters/StatusQueryParam'
        - $ref: '#/components/parameters/TypeQueryParam'
        - $ref: '#/components/parameters/ActivationDateQueryParam'
        - $ref: '#/components/parameters/DeactivationDateQueryParam'
        - $ref: '#/components/parameters/CommercialTransactionIdQueryParam'
        - name: provider_service_id
          in: query
          description: Provider service ID the Max subscription is linked to.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaxSet'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/subscriptions/netflix/{subscriptionId}':
    get:
      tags:
        - Netflix
      summary: Get Netflix subscription by ID
      description: Get a Netflix subscription by its unique identifier
      operationId: getNetflixSubscriptionById
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Netflix'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/SubscriptionNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'
    patch:
      tags:
        - Netflix
      summary: Patch Netflix subscription
      description: Apply patch operations to a Netflix subscription
      operationId: patchNetflix
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OperationsSet'
      responses:
        '200':
          description: Netflix subscription patched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Netflix'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/SubscriptionNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/bundles/{bundleId}/subscriptions/netflix':
    get:
      tags:
        - Netflix
      summary: Search Netflix subscriptions by bundle
      description: Search Netflix subscriptions within a specific bundle
      operationId: getNetflixSubscriptionListByBundle
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/BundleIdPathParam'
        - $ref: '#/components/parameters/OffsetQueryParam'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/LegacyIdQueryParam'
        - $ref: '#/components/parameters/AccountIdQueryParam'
        - $ref: '#/components/parameters/MandatoryQueryParam'
        - $ref: '#/components/parameters/StatusQueryParam'
        - $ref: '#/components/parameters/TypeQueryParam'
        - $ref: '#/components/parameters/ActivationDateQueryParam'
        - $ref: '#/components/parameters/DeactivationDateQueryParam'
        - $ref: '#/components/parameters/CommercialTransactionIdQueryParam'
        - name: provider_service_id
          in: query
          description: Provider service ID the Netflix subscription is linked to.
          required: false
          schema:
            type: string
        - name: registration_email
          in: query
          description: Registration email the Netflix subscription is linked to.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NetflixSet'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/subscriptions/orange_tv/{subscriptionId}':
    get:
      tags:
        - Orange TV
      summary: Get Orange TV subscription by ID
      description: Get an Orange TV subscription by its unique identifier
      operationId: getOrangeTvSubscriptionById
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrangeTv'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/SubscriptionNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'
    patch:
      tags:
        - Orange TV
      summary: Patch Orange TV subscription
      description: Apply patch operations to an Orange TV subscription
      operationId: patchOrangeTv
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OperationsSet'
      responses:
        '200':
          description: Orange TV subscription patched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrangeTv'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/SubscriptionNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/bundles/{bundleId}/subscriptions/orange_tv':
    get:
      tags:
        - Orange TV
      summary: Search Orange TV subscriptions by bundle
      description: Search Orange TV subscriptions within a specific bundle
      operationId: getOrangeTvSubscriptionListByBundle
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/BundleIdPathParam'
        - $ref: '#/components/parameters/OffsetQueryParam'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/LegacyIdQueryParam'
        - $ref: '#/components/parameters/AccountIdQueryParam'
        - $ref: '#/components/parameters/MandatoryQueryParam'
        - $ref: '#/components/parameters/StatusQueryParam'
        - $ref: '#/components/parameters/TypeQueryParam'
        - $ref: '#/components/parameters/ActivationDateQueryParam'
        - $ref: '#/components/parameters/DeactivationDateQueryParam'
        - $ref: '#/components/parameters/CommercialTransactionIdQueryParam'
        - name: registration_email
          in: query
          description: Registration email the Orange TV subscription is linked to.
          required: false
          schema:
            type: string
        - name: provider_service_id
          in: query
          description: Provider service ID the Orange TV subscription is linked to.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrangeTvSet'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/subscriptions/agile_tv/{subscriptionId}':
    get:
      tags:
        - Agile TV
      summary: Get AgileTv subscription
      description: Get AgileTv subscription by id, including specific type data
      operationId: getAgileTvSubscriptionById
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgileTv'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/SubscriptionNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

    patch:
      tags:
        - Agile TV
      summary: Update AgileTv subscription
      description: Update specific data of an AgileTv subscription
      operationId: patchAgileTv
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
      requestBody:
        description: Array of operations to apply to AgileTv specific data
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OperationsSet'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgileTv'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/SubscriptionNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/subscriptions/{subscriptionId}/add_ons':
    get:
      tags:
        - AddOns
      summary: Get subscription add-ons
      description: Get add-ons (value added services) associated to the subscription
      operationId: getSubscriptionAddOnList
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
        - $ref: '#/components/parameters/OffsetQueryParam'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/ActivationDateQueryParam'
        - $ref: '#/components/parameters/LegacyAddOnIdQueryParam'
      responses:
        '200':
          description: Add-ons associated to the subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddOnsSet'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/SubscriptionNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/subscriptions/{subscriptionId}/devices':
    get:
      tags:
        - Devices
      summary: Get subscription devices
      description: Get all subscription devices associated to the subscription
      operationId: getSubscriptionDeviceList
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
        - name: mac_address
          in: query
          required: false
          description: Mac address filter
          schema:
            type: string
          example: 00-B0-D0-63-C2-26
        - name: serial_number
          in: query
          required: false
          description: Serial number filter
          schema:
            type: string
          example: SN-48392A7F4B
      responses:
        '200':
          description: Devices found for the subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DevicesSet'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/SubscriptionNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/subscriptions/{subscriptionId}/promotions':
    post:
      tags:
        - Promotions
      summary: Add subscription promotion
      description: Add a new promotion to an existing subscription
      operationId: addSubscriptionPromotion
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
        - $ref: '#/components/parameters/OriginUserHeaderParam'
        - $ref: '#/components/parameters/OriginSystemHeaderParam'
      requestBody:
        description: Promotion input data
        content:
          application/json:
            examples:
              Promotion:
                description: Adding a Promotion to an existing subscription
                value:
                  catalogue_promotion_id: "1572"
                  origin: EXISTING_CLIENT
            schema:
              $ref: '#/components/schemas/PromotionRequest'
        required: true
      responses:
        '201':
          description: Promotion successfully added to the subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Promotion'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/SubscriptionNotFound'
        '409':
          $ref: '#/components/responses/PromotionAlreadyExists'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'
    get:
      tags:
        - Promotions
      summary: Get subscription promotions
      description: Get promotions associated to the subscription
      operationId: getSubscriptionPromotionList
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
        - $ref: '#/components/parameters/OffsetQueryParam'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/ActivationDateQueryParam'
        - $ref: '#/components/parameters/ExpirationDateQueryParam'
        - $ref: '#/components/parameters/PromotionStatusQueryParam'
        - $ref: '#/components/parameters/BundleIdQueryParam'
        - $ref: '#/components/parameters/CataloguePromotionIdQueryParam'
      responses:
        '200':
          description: Promotions associated to the subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromotionsSet'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/SubscriptionNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/subscriptions/{subscriptionId}/bonuses':
    get:
      tags:
        - Bonuses
      summary: Get subscription bonuses
      description: Get bonuses associated to the subscription
      operationId: getSubscriptionBonusList
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
        - $ref: '#/components/parameters/OffsetQueryParam'
        - $ref: '#/components/parameters/LimitQueryParam'
      responses:
        '200':
          description: Bonuses associated to the subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BonusesSet'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/SubscriptionNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/subscriptions/{subscriptionId}/add_ons/{addonId}/promotions':
    get:
      tags:
        - Promotions
      summary: Get add-on promotions
      description: Get all promotions associated with an add-on
      operationId: getAddOnPromotionList
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
        - $ref: '#/components/parameters/AddOnIdPathParam'
        - $ref: '#/components/parameters/OffsetQueryParam'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/ActivationDateQueryParam'
        - $ref: '#/components/parameters/ExpirationDateQueryParam'
        - $ref: '#/components/parameters/PromotionStatusQueryParam'
      responses:
        '200':
          description: Promotions found for the add-on
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromotionsSet'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/AddOnNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/subscriptions/{subscriptionId}/add_ons/{addonId}':
    patch:
      tags:
        - AddOns
      summary: Update subscription add-on
      description: Update specific data of a subscription add-on
      operationId: patchSubscriptionAddOn
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
        - $ref: '#/components/parameters/AddOnIdPathParam'
      requestBody:
        description: Array of operations to apply to add-on data
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OperationsSet'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddOn'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/AddOnNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

components:
  schemas:
    BundlesSet:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Bundle'
      allOf:
        - $ref: '#/components/schemas/PaginationData'
        - type: object

    Bundle:
      type: object
      required:
        - id
        - catalogue_bundled_product_id
        - creation_system
        - creation_user
      properties:
        catalogue_bundled_product_id:
          type: string
          description: Bundled product id according to catalogue definition
          example: 8432
        account_id:
          type: string
          description: Unique identifier of the account
          example: ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39
          format: uuid
        dealer_id:
          type: string
          writeOnly: true
          description: |
            Dealer id. Required if 'external_sell_id' is not provided.
          example: "245655"
        id:
          type: string
          description: Unique identifier of the subscriptions bundle
          readOnly: true
          example: ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39
        legacy_id:
          type: integer
          description: Legacy unique identifier of the subscriptions bundle
          readOnly: true
          example: 5345
        status:
          description: |
            Bundle status, check https://developers.masstack.com/en/guides/subscriptions/lifecycle for more information
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/LifeCycleStatus'
        last_status_update:
          type: string
          description: Last status update date and time. Format according to ISO 8601
          readOnly: true
          format: date-time
          example: 2023-01-05T03:30:15Z
        last_status_reason:
          type: string
          description: |
            Reason for the last status update according to defined values. Check possible values in status table
            in https://developers.masstack.com/en/guides/subscriptions/lifecycle.
          readOnly: true
          example: FRAUD_CHECK_ONGOING
        creation_date:
          type: string
          description: Subscription creation date and time. Format according to ISO 8601
          readOnly: true
          format: date-time
          example: 2022-12-01T00:00:00Z
        creation_system:
          type: string
          description: |
            Info about the system that requested the bundle creation. It contains the mas-stack authentication audience info
          readOnly: true
          example: killflex.auth.masmovil.com
        creation_user:
          type: string
          description: Info about the specific user that requested the bundle creation
          readOnly: true
          example: john.doe@masmovil.com
        activation_date:
          type: string
          description: |
            Activation date and time, bundle is considered chargeable and available for the user from 
            this time on. Format according to ISO 8601
          readOnly: true
          format: date-time
          example: 2023-01-01T00:00:00Z
        deactivation_date:
          type: string
          description: |
            Deactivation date and time, bundle is considered cancelled or inactive for the user from this time on.
            Format according to ISO 8601
          readOnly: true
          format: date-time
          example: 2025-01-05T03:30:15Z

    Subscription:
      type: object
      required:
        - id
        - type
        - status
        - creation_date
        - creation_system
        - creation_user
        - last_updated_date
        - last_status_update
        - pre_scoring_id
        - last_status_reason
        - account_id
        - commercial_transaction_id
      properties:
        id:
          type: string
          description: Unique identifier of the subscription
          readOnly: true
          format: uuid
          example: ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39
        legacy_id:
          type: integer
          description: Legacy unique identifier of the subscription
          readOnly: true
          example: 54
        type:
          description: Subscription type
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/SubscriptionType'
        catalogue_commercial_product_id:
          type: string
          description: |
            Commercial product id according to catalogue definition regardless of the bundle the subscription is included in
          example: "7125"
        status:
          description: Subscription status, check https://developers.masstack.com/en/guides/subscriptions/lifecycle for more information
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/LifeCycleStatus'
        promotions:
          type: array
          description: Ids of applicable promotions according to catalogue definition
          writeOnly: true
          items:
            $ref: '#/components/schemas/Promotion'
        add_ons:
          type: array
          description: Ids of applicable add-ons(value added services) according to catalogue definition
          writeOnly: true
          items:
            $ref: '#/components/schemas/AddOn'
        free_units_packages:
          type: array
          description: Ids of free units packages according to catalogue definition
          writeOnly: true
          items:
            $ref: '#/components/schemas/FreeUnitsPackage'
        devices:
          type: array
          description: Info about devices associated to the subscription
          writeOnly: true
          items:
            $ref: '#/components/schemas/Device'
        last_status_update:
          type: string
          description: Last status update date and time. Format according to ISO 8601
          readOnly: true
          format: date-time
          example: 2023-01-05T03:30:15Z
        last_status_reason:
          type: string
          description: |
            Reason for the last status update according to defined values. Check possible values in STATUS/STATUS table
            in https://developers.masstack.com/en/guides/subscriptions/lifecycle.
          example: SUBSCRIPTION_ADDED_TO_BUNDLE
        activation_date:
          type: string
          description: |
            Activation date and time, subscription is considered chargeable and available for the user from 
            this time on. Format according to ISO 8601
          readOnly: true
          format: date-time
          example: 2023-01-01T00:00:00Z
        deactivation_date:
          type: string
          description: |
            Deactivation date and time, subscription is considered cancelled or inactive for the user from this time on.
            Format according to ISO 8601
          readOnly: true
          format: date-time
          example: 2025-01-05T03:30:15Z
        account_id:
          type: string
          description: Unique identifier of the account
          example: ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39
          format: uuid
        bundle_related_info:
          $ref: '#/components/schemas/SubscriptionBundleRelation'
        creation_date:
          type: string
          description: Subscription creation date and time. Format according to ISO 8601
          readOnly: true
          format: date-time
          example: 2022-12-01T00:00:00Z
        creation_system:
          type: string
          description: |
            Info about the system/frontend originating the subscription creation. It contains the mas-stack authentication 
            audience info for mas-stack authenticated subscription creation or N/A for others
          readOnly: true
          example: killflex.auth.masmovil.com
        creation_user:
          type: string
          description: |
            Info about the specific user that requested the subscription creation. It contains the mas-stack 
            authentication subject info for mas-stack authenticated subscription creation, other user info for 
            subscriptions created by legacy systems if available or N/A if not available
          readOnly: true
          example: john.doe@masmovil.com
        last_updated_date:
          type: string
          description: Date and time when any field of the subscription was last updated. Format according to ISO 8601
          readOnly: true
          format: date-time
          example: 2023-01-08T12:00:05Z
        deactivation_system:
          type: string
          description: |
            Info about the system/frontend originating the subscription deactivation. It contains the mas-stack 
            authentication audience info for mas-stack authenticated deactivation or other user info for legacy systems 
            if available
          readOnly: true
          example: killflex.auth.masmovil.com
        deactivation_user:
          type: string
          description: |
            Info about the specific user that requested the subscription deactivation. It contains the mas-stack 
            authentication subject info for mas-stack authenticated subscription deactivation, other user info for 
            subscriptions created by legacy systems if available or N/A if not available
          readOnly: true
          example: john.doe@masmovil.com
        bundles_history:
          type: array
          description: History of bundles the subscription has been part of
          readOnly: true
          items:
            $ref: '#/components/schemas/SubscriptionBundleHistory'
        commercial_transaction_id:
          type: string
          description: Unique identifier of the last associated commercial transaction
          example: "ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39"

    LifeCycleStatus:
      type: string
      enum:
        - REQUESTED
        - ON_HOLD
        - PROVISIONING
        - ACTIVE
        - DEACTIVATING
        - DEACTIVATED
        - CANCELLING
        - CANCELLED
      example: ACTIVE

    SubscriptionStatusFilterEnum:
      type: object
      properties:
        eq:
          allOf:
            - $ref: '#/components/schemas/LifeCycleStatus'
          description: Filter by exact status
        in:
          type: array
          items:
            $ref: '#/components/schemas/LifeCycleStatus'
          description: Filter by multiple statuses

    PromotionStatusFilterEnum:
      type: object
      properties:
        eq:
          allOf:
            - $ref: '#/components/schemas/PromotionStatus'
          description: Filter by exact promotion status
        in:
          type: array
          items:
            $ref: '#/components/schemas/PromotionStatus'
          description: Filter by multiple promotion statuses

    SubscriptionBundleHistory:
      type: object
      properties:
        bundle_id:
          type: string
          description: Unique identifier of the bundle
          readOnly: true
          example: ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39
          format: uuid
        legacy_bundle_id:
          type: integer
          description: Legacy unique identifier of the bundle
          readOnly: true
          example: 54
        start_date:
          type: string
          description: Date and time when the subscription was added to the bundle. Format according to ISO 8601
          readOnly: true
          format: date-time
          example: 2022-12-01T00:00:00Z
        end_date:
          type: string
          description: Date and time when the subscription was removed from the bundle. Format according to ISO 8601
          readOnly: true
          format: date-time
          example: 2023-01-05T03:30:15Z

    DateFilterEnum:
      type: object
      properties:
        eq:
          type: string
          format: date-time
        lt:
          type: string
          format: date-time
        lte:
          type: string
          format: date-time
        gt:
          type: string
          format: date-time
        gte:
          type: string
          format: date-time

    PaginationData:
      type: object
      required:
        - limit
        - offset
        - total
      properties:
        limit:
          type: integer
          description: Limit of items per response
          example: 5
        offset:
          type: integer
          description: Limit of items per response
          example: 15
        total:
          type: integer
          description: Total number of results for search criteria
          example: 33

    PromotionStatus:
      type: string
      enum:
        - REQUESTED
        - ACTIVE
        - CANCELLED
        - DEACTIVATED
        - EXPIRED
      example: ACTIVE

    BonusStatus:
      type: string
      enum:
        - REQUESTED
        - ACTIVE
        - CANCELLED
        - DEACTIVATED
      example: ACTIVE

    SubscriptionType:
      type: string
      x-extensible-enum:
        - MOBILE
        - BROADBAND
        - LANDLINE
        - TV
        - SECURITY
        - DATA_SHARING
        - MULTISIM
        - DEVICE_INSURANCE
        - NETFLIX
        - APPLE_WATCH
        - AMAZON_PRIME
        - MAX
        - ORANGE_TV
        - DISNEY
      example: NETFLIX
      readOnly: true

    DeviceSwapRequest:
      type: object
      description: Device swap request. Exactly one of new_serial_number or transfer_with must be provided.
      properties:
        new_serial_number:
          type: string
          description: New device serial number for automatic swaps
          example: ABC123456789
        transfer_with:
          type: string
          format: uuid
          description: Device identifier to transfer with
          example: fd2fcd90-2218-4ef1-917b-7ce5f35eee1c
      oneOf:
        - required:
            - new_serial_number
        - required:
            - transfer_with

    Address:
      type: object
      properties:
        street_type:
          type: string
          description: Street type
          example: CALLE
        address_code:
          type: string
          description: Address code
          example: "123142344325235   1215"
        street_name:
          type: string
          description: Street name
          example: CALLE MADRID
        house_number:
          type: string
          description: House number
          example: "1"
        additional_info:
          type: string
          description: Additional address information
          example: PLANTA 3, PUERTA 1
        city:
          type: string
          description: City
          example: MADRID
        province:
          type: string
          description: Province
          example: MADRID
        country:
          type: string
          description: Country
          example: ES
        post_code:
          type: string
          description: Postal code
          example: "28155"

    Broadband:
      type: object
      allOf:
        - $ref: '#/components/schemas/Subscription'
        - type: object
      properties:
        access_id:
          type: string
          description: Broadband access id
          readOnly: true
          example: J24030AAA925
        territory_owner:
          type: string
          description: Broadband territory owner
          readOnly: true
          example: FIBOR01
        legacy_service_id:
          type: string
          description: Legacy service id
          readOnly: true
          example: MYSIM_528310
        installation_address:
          allOf:
            - $ref: '#/components/schemas/Address'
          readOnly: true

    AmazonPrime:
      type: object
      allOf:
        - $ref: '#/components/schemas/Subscription'
        - type: object
      properties:
        provider_service_id:
          type: string
          description: "Amazon Prime internal ID that identifies the subscription for any required operation to be performed on it, e.g: activate, update, cancel, etc."
          example: "d2af0bd9-c71b-42aa-a258-c9d9dc734bfc"
          readOnly: true
        provider_product_id:
          type: string
          description: Amazon Prime product ID according to its provided catalog definition, relevant for B2B billing.
          example: PRIME_1M_BUNDLE
          readOnly: true
        provider_bundle_id:
          type: string
          description: "Amazon Prime internal ID that uniquely identifies the subscription once it has been activated and allows subsequent operations such as info check"
          example: "e773dac9-4b13-4287-bb97-a773200de581"
          readOnly: true
        provider_tier:
          type: string
          description: |
            Amazon Prime tier for the subscription according to its internal promotions situation (e.g: free trial),relevant for its B2B billing. Values defined by Amazon
          example: prime_1_months_hard_offer
          readOnly: true

    Max:
      type: object
      allOf:
        - $ref: '#/components/schemas/Subscription'
        - type: object
      properties:
        provider_service_id:
          type: string
          description: "Max internal ID that identifies the subscription for any required operation to be performed on it, e.g: activate, update, cancel, etc."
          example: "d2af0bd9-c71b-42aa-a258-c9d9dc734bfc"
          readOnly: true
        provider_product_id:
          type: string
          description: Max product ID according to its provided catalog definition, relevant for B2B billing.
          example: "beam-max-svod-monthly"
          readOnly: true

    AgileTvSet:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AgileTv'
      allOf:
        - $ref: '#/components/schemas/PaginationData'
        - type: object

    OrangeTvSet:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrangeTv'
      allOf:
        - $ref: '#/components/schemas/PaginationData'
        - type: object

    AmazonPrimeSet:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AmazonPrime'
      allOf:
        - $ref: '#/components/schemas/PaginationData'
        - type: object

    BroadbandSet:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Broadband'
      allOf:
        - $ref: '#/components/schemas/PaginationData'
        - type: object

    DisneySet:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Disney'
      allOf:
        - $ref: '#/components/schemas/PaginationData'
        - type: object

    MaxSet:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Max'
      allOf:
        - $ref: '#/components/schemas/PaginationData'
        - type: object

    NetflixSet:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Netflix'
      allOf:
        - $ref: '#/components/schemas/PaginationData'
        - type: object

    MobileSet:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Mobile'
      allOf:
        - $ref: '#/components/schemas/PaginationData'
        - type: object

    TvSet:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Tv'
      allOf:
        - $ref: '#/components/schemas/PaginationData'
        - type: object

    AddOnsSet:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AddOn'
      allOf:
        - $ref: '#/components/schemas/PaginationData'
        - type: object

    BonusesSet:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Bonus'
      allOf:
        - $ref: '#/components/schemas/PaginationData'
        - type: object

    SubscriptionsSet:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Subscription'
      allOf:
        - $ref: '#/components/schemas/PaginationData'
        - type: object

    OrangeTv:
      type: object
      allOf:
        - $ref: '#/components/schemas/Subscription'
        - type: object
      required:
        - registration_email
        - requires_installation
      properties:
        registration_email:
          type: string
          description: Email address linked to the Orange TV subscription
          example: john.doe@mail.com
        provider_service_id:
          type: string
          description: "Orange Tv internal ID that identifies the subscription for any required operation to be performed on it, e.g: activate, update, cancel, etc."
          example: yoigo123456789
          readOnly: true
        provider_product_id:
          type: string
          description: Orange Tv product ID according to its provided catalog definition, relevant for B2B billing.
          example: SP_OFFER_0200000
          readOnly: true
        requires_installation:
          type: boolean
          description: Indicates if the Orange TV STB must be send via installations (true) or logistics (false)
          writeOnly: true

    Disney:
      type: object
      allOf:
        - $ref: '#/components/schemas/Subscription'
        - type: object
      properties:
        provider_user_id:
          type: string
          description: The provider user identifier.
          example: "d2af0bd9-c71b-42aa-a258-c9d9dc734bfc"
          readOnly: true
        provider_service_id:
          type: string
          description: The provider service identifier.
          example: "d2af0bd9-c71b-42aa-a258-c9d9dc734bfc"
          readOnly: true
        provider_product_id:
          type: string
          description: The provider product identifier.
          example: "com.disney.yoigo.es.bundle.standard"
          readOnly: true

    AgileTv:
      type: object
      allOf:
        - $ref: '#/components/schemas/Subscription'
        - type: object
      required:
        - requires_installation
      properties:
        provider_service_id:
          type: string
          description: "Agile Tv internal ID that identifies the subscription for any required operation to be performed on it, e.g: activate, update, cancel, etc."
          example: yoigo123456789
          readOnly: true
        provider_product_id:
          type: string
          description: Agile Tv product ID according to its provided catalog definition, relevant for B2B billing.
          example: SP_OFFER_0200000
          readOnly: true
        is_primary:
          type: boolean
          description: Indicates if the subscription is the primary one for the bundle
          example: true
          readOnly: true
        requires_installation:
          type: boolean
          description: Indicates if the Agile TV STB must be send via installations (true) or logistics (false)
          writeOnly: true

    Netflix:
      type: object
      allOf:
        - $ref: '#/components/schemas/Subscription'
        - type: object
      properties:
        provider_service_id:
          type: string
          description: The provider service identifier.
          example: "7b7b7b7-b7b7-b7b7-b7b7-b7b7b7b7b7b7"
          readOnly: true
        provider_bundle_id:
          type: string
          description: The provider bundle identifier.
          example: "d2af0bd9-c71b-42aa-a258-c9d9dc734bfc"
          readOnly: true
        provider_product_id:
          type: string
          description: The provider product identifier.
          example: "d2af0bd9-c71b-42aa-a258-c9d9dc734bfc"
          readOnly: true

    Mobile:
      type: object
      allOf:
        - $ref: '#/components/schemas/Subscription'
        - type: object
      properties:
        msisdn:
          type: string
          description: MSISDN (Mobile Station International Subscriber Directory Number) formatted following E.164 format
          example: +34611223344
          readOnly: true
        sim:
          allOf:
            - $ref: '#/components/schemas/Sim'
          readOnly: true

    Tv:
      type: object
      allOf:
        - $ref: '#/components/schemas/Subscription'
        - type: object
      properties:
        registration_email:
          type: string
          format: email
          description: Email address linked to the TV subscription.
          example: john.doe@mail.com
          readOnly: true
        registration_phone:
          type: string
          description: Registration phone linked to the TV subscription.
          example: "600123123"
          readOnly: true

    Sim:
      type: object
      description: SIM card information
      properties:
        iccid:
          type: string
          description: Integrated Circuit Card Identifier
          example: "8934000000000000002"
        imsi:
          type: string
          description: IMSI (International Mobile Subscriber Identity)
          example: "214040000000000"
        type:
          type: string
          description: SIM card type
          enum:
            - SIM
            - MICROSIM
            - ESIM
            - NANOSIM

    FreeUnitsPackage:
      type: object
      required:
        - id
        - catalogue_free_units_packages_id
        - activation_date
      properties:
        id:
          type: string
          description: Assigned Free Units Package ID
          readOnly: true
          example: ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39
        legacy_id:
          type: integer
          description: Assigned Free Units Package legacy ID
          readOnly: true
          example: 457345
        catalogue_free_units_package_id:
          type: string
          description: Catalogue free units package ID
          example: "124"
        activation_date:
          type: string
          description: Activation date and time of the package. Format according to ISO 8601
          readOnly: true
          format: date-time
          example: 2023-01-01T00:00:00Z
        deactivation_date:
          type: string
          description: Deactivation date and time of the package. Format according to ISO 8601
          readOnly: true
          format: date-time

    Bonus:
      type: object
      required:
        - id
        - catalogue_free_units_package_id
        - activation_date
      properties:
        id:
          type: string
          description: Assigned subscription bonus ID
          readOnly: true
          example: ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39
        legacy_id:
          type: integer
          description: Assigned legacy subscription bonus ID
          readOnly: true
          example: 457345
        catalogue_free_units_package_id:
          type: string
          description: Catalogue free units package ID
          example: "36"
        last_updated_date:
          type: string
          description: Date and time when any field of the bonus was last updated. Format according to ISO 8601
          readOnly: true
          format: date-time
          example: 2023-01-08T12:00:05Z
        last_updated_system:
          type: string
          description: Info about the system that last updated the bonus. It contains the mas-stack authentication audience info. N/A if not available
          readOnly: true
          example: killflex.auth.masmovil.com
        last_updated_user:
          type: string
          description: Info about the specific user that last updated the bonus. N/A if not available
          readOnly: true
          example: john.doe@masorange.es
        status:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/BonusStatus'
          type: string
        activation_date:
          type: string
          description: Activation date and time of the bonus. Format according to ISO 8601
          readOnly: true
          format: date-time
          example: 2023-01-01T00:00:00Z
        deactivation_date:
          type: string
          description: Deactivation date and time of the bonus. Format according to ISO 8601
          readOnly: true
          format: date-time
        deactivation_system:
          type: string
          description: |
            Info about the system that requested the bonus deactivation. It contains the mas-stack authentication
            audience info when deactivation is requested by mas-stack authenticated user, N/A if not available
          readOnly: true
          example: killflex.auth.masmovil.com
        deactivation_user:
          type: string
          description: |
            Info about the specific user that requested the bonus deactivation. It contains the mas-stack authentication
            subject info when deactivation was requested by mas-stack authenticated user, other user info for legacy
            systems deactivations if available or N/A otherwise
          readOnly: true
          example: john.doe@masorange.es

    Device:
      type: object
      description: Devices associated to the subscription
      required:
        - catalogue_commercial_device_id
        - account_id
      properties:
        id:
          type: string
          format: uuid
          description: Device unique identifier
          example: "ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39"
          readOnly: true
        legacy_id:
          type: integer
          description: Legacy unique identifier of the device associated with the subscription
          example: 756402
          readOnly: true
        catalogue_commercial_device_id:
          type: string
          description: "Commercial device id according to catalogue definition"
          example: "CDCVPU_150f5badaa706651e67c59061d373d7e7e"
        catalogue_device_id:
          type: string
          description: "Device id according to catalogue definition"
          readOnly: true
          example: "P09712MRC"
        logistics_shipping_order_id:
          type: string
          description: "Id of the shipping order related to the device according to logistics"
          example: "18395"
          readOnly: true
        logistics_pickup_order_id:
          type: string
          description: "Id of the pickup order related to the device according to reverse logistics"
          example: "P0000001"
          readOnly: true
        in_store_delivery_date:
          type: string
          description: In shop delivery date to the customer. Format according to ISO 8601.
          readOnly: true
          format: date-time
          example: 2025-01-05T03:30:15Z
        in_store_returned_date:
          type: string
          description: In shop returned date. Format according to ISO 8601.
          readOnly: true
          format: date-time
          example: 2025-01-05T03:30:15Z
        serial_number:
          type: string
          description: The serial number or any alphanumeric identifier of a particular device
          example: 9876543-AB-345
        mac_address:
          type: string
          description: A unique identifier assigned to the device network interface controller
          example: 00-B0-D0-63-C2-26
        imei:
          type: string
          description: The International Mobile Equipment Identity of the device
          example: AA-BBBBBB-CCCCCC-D
        acquisition_type:
          type: string
          description: Specifies the type of acquisition for the device
          enum:
            - BORROWED
            - FINANCED
            - ONE_TIME_PAYMENT
          example: BORROWED
          readOnly: true
        commitments:
          type: array
          items:
            $ref: '#/components/schemas/Commitment'
        insurable_amount:
          type: number
          description: The insurable value of the device, representing the maximum coverage amount for insurance purposes. A null value indicates that the device is not insurable
          example: 135.49
          writeOnly: true
        status:
          description: |
            Device status derived from Apollo terminal and return data.
            See https://developers.masstack.com/en/guides/subscriptions/device-status for enum semantics and
            Device Insurance validation behavior.
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/DeviceStatus'
        account_id:
          type: string
          description: Unique identifier of the account
          example: ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39
          format: uuid
          readOnly: true
        promotions:
          type: array
          description: Promotions associated to the device according to catalogue definition
          writeOnly: true
          items:
            $ref: '#/components/schemas/Promotion'

    DevicesSet:
      type: array
      items:
        $ref: '#/components/schemas/Device'

    DeviceStatus:
      type: string
      description: |
        Status of a device associated with a subscription.
        - `ACTIVE`: Device is currently valid for the subscription.
        - `CANCELLED`: Device was cancelled or desisted in legacy Apollo; includes `STATUSID` 49 and 127.
        - `RETURNED`: Device is known as returned.
        - `UNKNOWN`: Device state cannot be safely inferred.
        For Device Insurance, only `CANCELLED` is rejected by status validation; every other status continues to
        catalogue, duplicate insurance, and feasibility validations.
      enum:
        - ACTIVE
        - CANCELLED
        - RETURNED
        - UNKNOWN
      example: ACTIVE

    IdentificationDocument:
      type: object
      description: Identification document
      properties:
        id_type:
          type: string
          enum:
            - NIF
            - PASSPORT
            - CIF
            - NIE
            - UNKNOWN
          example: NIF
        id:
          type: string
          example: "5012341234"

    SubscriptionBundleRelation:
      type: object
      required:
        - id
        - catalogue_bundled_product_id
        - catalogue_bundled_commercial_product_id
        - mandatory
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the bundle the subscription is included in
          example: abcf20cb-35df-4ffe-bca6-c0ed0c28cb00
        legacy_id:
          type: integer
          description: Legacy unique identifier of the bundle the subscription is included in
          readOnly: true
          example: 790224234
        catalogue_bundled_product_id:
          type: string
          description: Bundle product id according to catalogue definition
          example: "8342"
        catalogue_bundled_commercial_product_id:
          type: string
          description: Bundle commercial product id associated to subscription according to catalogue definition
          example: 8432_BUNDLED_3P
        mandatory:
          type: boolean
          description: Specifies if subscription is mandatory to keep the associated bundle
          example: true

    Commitment:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          format: uuid
          description: Acquired commitment id
          readOnly: true
          example: ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39
        legacy_id:
          type: integer
          description: Legacy id for acquired commitment linked MySim/Apollo storage
          readOnly: true
          example: 345
        catalogue_term_id:
          type: string
          description: Catalogue term ID
          example: "124"
          readOnly: true
        expiration_date:
          type: string
          description: End date according to ISO 8601
          readOnly: true
          format: date-time
          example: 2025-01-05T03:30:15Z
        cancellation_date:
          type: string
          description: Cancellation date according to ISO 8601
          readOnly: true
          format: date-time
          example: 2025-02-13T10:35:05Z
        cancellation_system:
          type: string
          description: Info about the system that requested the commitment cancellation. It contains the mas-stack authentication audience info.  N/A if not available
          readOnly: true
          example: killflex.auth.masmovil.com
        cancellation_user:
          type: string
          readOnly: true
          description: Info about the specific user that requested the commitment cancellation. N/A if not available
          example: john.doe@masorange.es

    PromotionRequest:
      type: object
      required:
        - catalogue_promotion_id
      properties:
        catalogue_promotion_id:
          type: string
          description: Catalogue promotion ID
          example: "124"
        origin:
          type: string
          description: Origin used to validate the promotion in catalogue
          enum:
            - MIGRATION
            - EXISTING_CLIENT
            - UNKNOWN
          example: EXISTING_CLIENT
        activation_date:
          type: string
          description: Promotion activation date. Format according to ISO 8601
          format: date-time
          example: 2022-12-01T00:00:00Z

    Promotion:
      type: object
      required:
        - id
        - catalogue_promotion_id
        - creation_date
        - creation_system
        - creation_user
        - last_updated_date
        - status
      properties:
        id:
          type: string
          description: Promotion ID
          readOnly: true
          example: ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39
        legacy_id:
          type: integer
          description: Legacy promotion ID
          readOnly: true
          example: 457345
        catalogue_promotion_id:
          type: string
          description: Catalogue promotion ID
          example: "124"
        commitments:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/Commitment'
        creation_date:
          type: string
          description: Promotion creation date. Format according to ISO 8601
          readOnly: true
          format: date-time
          example: 2022-12-01T00:00:00Z
        creation_system:
          type: string
          description: Info about the system that requested the promotion creation. It contains the mas-stack authentication audience info.  N/A if not available
          readOnly: true
          example: killflex.auth.masmovil.com
        creation_user:
          type: string
          readOnly: true
          description: Info about the specific user that requested the promotion creation. N/A if not available
          example: john.doe@masorange.es
        last_updated_date:
          type: string
          description: Date and time when any field of the promotion was last updated. Format according to ISO 8601
          readOnly: true
          format: date-time
          example: 2023-01-08T12:00:05Z
        status:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/PromotionStatus'
          type: string
        status_detail:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/PromotionStatusDetail'
          type: string
        activation_date:
          type: string
          description: Activation date and time the promotion is or will be available in the subscription. When provided, it is restricted to be between current billing cycle and less than a year from now. Format according to ISO 8601
          format: date-time
          example: 2023-01-01T00:00:00Z
        expiration_date:
          type: string
          description: The date and time when the promotion expires. Format according to ISO 8601.
          readOnly: true
          format: date-time
          example: 2025-01-05T03:30:15Z
        deactivation_date:
          type: string
          description: |
            Deactivation date and time, promotion is considered cancelled or inactive for the user from this time on.
            Format according to ISO 8601
          readOnly: true
          format: date-time
          example: 2025-01-05T03:30:15Z
        deactivation_system:
          type: string
          description: |
            Info about the system that requested the promotion deactivation. It contains the mas-stack authentication
            audience info when deactivation is requested by mas-stack authenticated user, N/A for legacy systems created
            promotions
          readOnly: true
          example: killflex.auth.masmovil.com
        deactivation_user:
          type: string
          description: |
            Info about the specific user that requested the promotion deactivation. It contains the mas-stack authentication
            subject info when deactivation was requested by mas-stack authenticated user, other user info for legacy 
            systems deactivations if available or N/A otherwise
          readOnly: true
          example: john.doe@masorange.es

    PromotionsSet:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Promotion'
      allOf:
        - $ref: '#/components/schemas/PaginationData'
        - type: object

    AddOn:
      type: object
      required:
        - id
        - catalogue_value_added_service_legacy_id
        - catalogue_value_added_service_id
        - creation_date
        - creation_system
        - creation_user
        - last_updated_date
        - status
      properties:
        id:
          type: string
          description: Add-on unique identifier
          readOnly: true
          example: ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39
        legacy_id:
          type: integer
          description: Legacy add-on id Linked to MySim/Apollo storage, to be deprecated.
          readOnly: true
          example: 457345
        catalogue_value_added_service_legacy_id:
          type: string
          description: MySim/Apollo related id for the Add-On catalogue resource definition
          example: "124"
        catalogue_value_added_service_id:
          type: string
          description: Catalogue add-on ID
          example: "124"
        promotions:
          type: array
          description: Ids of applicable promotions according to catalogue definition
          writeOnly: true
          items:
            $ref: '#/components/schemas/Promotion'
        creation_date:
          type: string
          description: add-on creation date. Format according to ISO 8601
          readOnly: true
          format: date-time
          example: 2022-12-01T00:00:00Z
        creation_system:
          type: string
          description: Info about the system that requested the addOn creation. It contains the mas-stack authentication audience info.  N/A if not available
          readOnly: true
          example: killflex.auth.masmovil.com
        creation_user:
          type: string
          readOnly: true
          description: Info about the specific user that requested the addON creation. N/A if not available
          example: john.doe@masorange.es
        last_updated_date:
          type: string
          description: Date and time when any field of the addOn was last updated. Format according to ISO 8601
          readOnly: true
          format: date-time
          example: 2023-01-08T12:00:05Z
        status:
          type: string
          description: Add-on status
          enum:
            - REQUESTED
            - ACTIVE
            - CANCELLED
            - DEACTIVATED
            - PROVISIONING
          readOnly: true
          example: "CANCELLED"
        activation_date:
          type: string
          format: date-time
          readOnly: true
          example: "2023-01-01T00:00:00Z"
        deactivation_date:
          type: string
          format: date-time
          example: "2025-01-05T03:30:15Z"
          readOnly: true
        deactivation_system:
          type: string
          example: "killflex.auth.masmovil.com"
          readOnly: true
        deactivation_user:
          type: string
          description: |
            Info about the specific user that requested the addOn deactivation. It contains the mas-stack authentication
            subject info when deactivation was requested by mas-stack authenticated user, other user info for legacy 
            systems deactivations if available or N/A otherwise
          readOnly: true
          example: john.doe@masorange.es
        provider_product_id:
          type: string
          description: External provider product identifier
          readOnly: true
          example: "provider_product_id"
        provider_service_id:
          type: string
          description: External provider service identifier
          readOnly: true
          example: "d2af0bd9c71b42aaa258c9d9dc734bfc"

    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetails'

    ErrorDetails:
      type: object
      required:
        - code
        - message
        - reference
      properties:
        code:
          type: string
          description: Error code having an entry in a domain dictionary
          example: FORBIDDEN_ORGANIZATION
        message:
          type: string
          description: Message of the error
          example: "Access to organization not allowed"
        reference:
          type: string
          description: Domain error dictionary location in the developer portal
          default: https://developers.masstack.com/en/guides/subscriptions/errorcatalogue

    SubscriptionDeactivationRequest:
      type: object
      required:
        - reason
      properties:
        reason:
          type: string
          enum:
            - ACCOUNT_MIGRATION
            - BUNDLE_CANCELLATION
            - BUNDLE_DEACTIVATION
            - BUNDLE_MIGRATION
            - FRAUD_CHECK_REJECTION
            - NON_PAYMENT
            - OTHER
            - PAYMENT_ERROR
            - PROVISIONING_ISSUE
            - SUBSCRIBER_RESIGNATION
            - DEACTIVATED_ON_THIRD_PARTY
            - AUTOMATICALLY_REMOVED
          description: Reason for the deactivation
          example: "SUBSCRIBER_RESIGNATION"
        promotion_commitments_to_cancel:
          type: array
          description: Promotion commitment IDs to cancel in the deactivation process
          items:
            type: string
            format: uuid
          example: [ "ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39" ]
        device_commitments_to_cancel:
          type: array
          description: Device commitment IDs to cancel in the deactivation process
          items:
            type: string
            format: uuid
          example: [ "ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39" ]
        add_on_commitments_to_cancel:
          type: array
          description: Add-on commitment IDs to cancel in the deactivation process
          items:
            type: string
            format: uuid
          example: [ "ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39" ]

    PromotionStatusDetail:
      type: string
      enum:
        - AUTOMATICALLY_ADDED
        - AUTOMATICALLY_REMOVED
        - BUNDLE_SALE
        - MANUALLY_ADDED
        - MANUALLY_REMOVED
        - OTHER
        - PROMOTION_INCOMPATIBILITY
        - SUBSCRIPTION_ADDED_TO_BUNDLE
        - SUBSCRIPTION_DEACTIVATION
      description: Detail for the promotion current status
      example: "SUBSCRIPTION_DEACTIVATION"

    SubscriptionCancellationRequest:
      type: object
      description: Cancellation request
      required:
        - reason
      properties:
        reason:
          type: string
          enum:
            - ACCOUNT_MIGRATION
            - BUNDLE_CANCELLATION
            - BUNDLE_DEACTIVATION
            - BUNDLE_MIGRATION
            - FRAUD_CHECK_REJECTION
            - EXPEDITION_CANCELLED
            - OTHER
            - PAYMENT_ERROR
            - PROVISIONING_ISSUE
            - SUBSCRIBER_RESIGNATION
            - AUTOMATICALLY_REMOVED
          description: Reason for the cancellation request
          example: "SUBSCRIBER_RESIGNATION"

    OperationsSet:
      type: array
      items:
        $ref: '#/components/schemas/Operation'

    Operation:
      type: object
      required:
        - op
        - path
        - value
      properties:
        op:
          type: string
          description: Operation to be performed on the entity
          enum:
            - replace
          example: "replace"
        path:
          type: string
          description: Path to the field to be updated
          example: "logistics_shipping_order_id"
        value:
          description: Value to use for the operation
          example: "new-shipping-order-id"

  responses:
    DefaultErrorResponse:
      description: Any client or server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: ERROR_CODE
            message: Error message
            reference: https://developers.masstack.com/en/guides/subscriptions/errorcatalogue
    SubscriptionNotFound:
      description: A subscription with the specified id was not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: SUBSCRIPTION_NOT_FOUND
            message: No subscription found with given id
            reference: https://developers.masstack.com/en/guides/subscriptions/errorcatalogue
    BundleNotFound:
      description: A bundle with the specified id was not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: BUNDLE_NOT_FOUND
            message: No bundle found with given id
            reference: https://developers.masstack.com/en/guides/subscriptions/errorcatalogue
    PromotionNotFound:
      description: A promotion with the specified id was not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: PROMOTION_NOT_FOUND
            message: No promotion found with given id
            reference: https://developers.masstack.com/en/guides/subscriptions/errorcatalogue
    PromotionAlreadyExists:
      description: Promotion already exists in the subscription
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: PROMOTION_ALREADY_EXISTS
            message: Promotion 1572 already exists
            reference: https://developers.masstack.com/en/guides/subscriptions/errorcatalogue
    DeviceNotFound:
      description: A device with the specified id was not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: DEVICE_NOT_FOUND
            message: No device found with given id
            reference: https://developers.masstack.com/en/guides/subscriptions/errorcatalogue
    BonusNotFound:
      description: A bonus with the specified id was not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: BONUS_NOT_FOUND
            message: No bonus found with given id
            reference: https://developers.masstack.com/en/guides/subscriptions/errorcatalogue
    ChangeRequestNotFound:
      description: A change request with the specified id was not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: CHANGE_REQUEST_NOT_FOUND
            message: No change request found with given id
            reference: https://developers.masstack.com/en/guides/subscriptions/errorcatalogue
    CommitmentNotFound:
      description: A commitment with the specified id was not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: COMMITMENT_NOT_FOUND
            message: No commitment found with given id
            reference: https://developers.masstack.com/en/guides/subscriptions/errorcatalogue
    AddOnNotFound:
      description: AddOn with the specified id was not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: ADD_ON_NOT_FOUND
            message: No addOn found with given id
            reference: https://developers.masstack.com/en/guides/subscriptions/errorcatalogue
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: INVALID_REQUEST
            message: The request is invalid
            reference: https://developers.masstack.com/en/guides/subscriptions/errorcatalogue
    ForbiddenAccess:
      description: Forbidden access
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: FORBIDDEN_ORGANIZATION
            message: Access to organization not allowed
            reference: https://developers.masstack.com/en/guides/subscriptions/errorcatalogue
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: DATABASE_ACCESS_ERROR
            message: The database is not accessible
            reference: https://developers.masstack.com/en/guides/subscriptions/errorcatalogue
    SubscriptionConflict:
      description: Subscription was modified by another process. Concurrent modification detected.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: CONFLICT
            message: Subscription was modified by another process. Please retry.
            reference: https://developers.masstack.com/en/guides/subscriptions/errorcatalogue
    ChangeRequestConflict:
      description: A change request for the subscription with the change requested is still in progress
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: CHANGE_REQUEST_CONFLICT
            message: A change request for the subscription with the change requested is still in progress
            reference: https://developers.masstack.com/en/guides/subscriptions/errorcatalogue
    UnsupportedSubscriptionType:
      description: The subscription type requested is not supported
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: UNSUPPORTED_SUBSCRIPTION_TYPE
            message: The requested subscription type is not supported
            reference: https://developers.masstack.com/en/guides/subscriptions/errorcatalogue

  parameters:
    OrgPathParam:
      in: path
      name: org
      description: Organization name
      required: true
      schema:
        type: string
      example: yoigo

    BundleIdPathParam:
      in: path
      name: bundleId
      description: Bundle identifier
      required: true
      schema:
        type: string
        format: uuid
      example: 7a15e304-c357-449b-bd58-bcfb43b3471d

    SubscriptionIdPathParam:
      in: path
      name: subscriptionId
      description: Subscription unique identifier
      required: true
      schema:
        type: string
        format: uuid
      example: ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39

    OriginUserHeaderParam:
      in: header
      name: x-auth-origin-sub
      schema:
        type: string

    OriginSystemHeaderParam:
      in: header
      name: x-auth-origin-aud
      schema:
        type: string


    PromotionIdPathParam:
      in: path
      name: promotionId
      description: Promotion unique identifier
      required: true
      schema:
        type: string
        format: uuid
      example: 27cdbb91-e380-4f83-a45f-94bf67400342

    CommitmentIdPathParam:
      in: path
      name: commitmentId
      description: Commitment unique identifier
      required: true
      schema:
        type: string
        format: uuid
      example: 00a96051-bb4a-498c-adab-95b1dd8e7222

    DeviceIdPathParam:
      in: path
      name: deviceId
      description: Device unique identifier
      required: true
      schema:
        type: string
        format: uuid
      example: fd2fcd90-2218-4ef1-917b-7ce5f35eee1c

    BonusIdPathParam:
      in: path
      name: bonusId
      description: Bonus unique identifier
      required: true
      schema:
        type: string
        format: uuid
      example: 0100cfa5-06e9-4572-976d-5287916adff1

    ChangeRequestIdPathParam:
      in: path
      name: changeRequestId
      description: Change request unique identifier
      required: true
      schema:
        type: string
        format: uuid
      example: 0100cfa5-06e9-4572-976d-5287916adff1

    AddOnIdPathParam:
      in: path
      name: addonId
      description: AddOn unique identifier
      required: true
      schema:
        type: string
        format: uuid
      example: 0100cfa5-06e9-4572-976d-5287916adff1

    ContractIdPathParam:
      in: path
      name: contractId
      description: Contract unique identifier
      required: true
      schema:
        type: string
        format: uuid
      example: a570614e-8a66-4d93-b329-7a2c9d6f0ce8

    LegacyIdQueryParam:
      in: query
      name: legacy_id
      description: Resource legacy ID
      required: false
      schema:
        type: integer
      example: 0

    OffsetQueryParam:
      in: query
      name: offset
      description: Pagination offset
      required: false
      schema:
        type: integer
      example: 0

    LimitQueryParam:
      in: query
      name: limit
      description: Pagination limit
      required: false
      schema:
        type: integer
      example: 50

    BundleIdQueryParam:
      name: bundle_id
      in: query
      description: Bundle id the subscription is linked to.
        to MySim/Apollo storage, to be deprecated.
      required: false
      schema:
        type: string
        format: uuid
      example: ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39

    LegacyAddOnIdQueryParam:
      name: legacy_add_on_id
      in: query
      description: AddOn id the subscription is linked to. Linked to MySim/Apollo storage, to be deprecated.
      required: false
      schema:
        type: integer
      example: 572234234

    AccountIdQueryParam:
      name: account_id
      in: query
      description: Account id the subscription is linked to.
      required: false
      schema:
        type: string
      example: ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39

    LegacyBundleIdQueryParam:
      name: legacy_bundle_id
      in: query
      description: Bundle id the subscription is linked to. Required if the legacy_id or account_id filters are not provided. Linked to MySim/Apollo storage, to be deprecated.
      required: false
      schema:
        type: integer
      example: 26245435

    MandatoryQueryParam:
      name: mandatory
      in: query
      description: Mandatory subscription filter
      required: false
      schema:
        type: boolean
      example: true

    StatusQueryParam:
      name: status
      in: query
      required: false
      description: Subscription status filter
      style: deepObject
      explode: true
      schema:
        $ref: '#/components/schemas/SubscriptionStatusFilterEnum'

    PromotionStatusQueryParam:
      name: status
      in: query
      required: false
      description: Promotion status filter
      style: deepObject
      explode: true
      schema:
        $ref: '#/components/schemas/PromotionStatusFilterEnum'

    TypeQueryParam:
      name: type
      in: query
      required: false
      description: Subscription type
      schema:
        $ref: '#/components/schemas/SubscriptionType'

    ActivationDateQueryParam:
      name: activation_date
      in: query
      description: |
        Resource activation date filter. Available filters are [eq, lt, lte, gt, gte]. Format according to ISO 8601
      required: false
      style: deepObject
      explode: true
      schema:
        $ref: '#/components/schemas/DateFilterEnum'
      example: 2023-01-05T03:30:15Z

    DeactivationDateQueryParam:
      name: deactivation_date
      in: query
      description: |
        Resource deactivation date filter. Available filters are [eq, lt, lte, gt, gte]. Format according to ISO 8601
      required: false
      style: deepObject
      explode: true
      schema:
        $ref: '#/components/schemas/DateFilterEnum'
      example: 2023-01-05T03:30:15Z

    ExpirationDateQueryParam:
      name: expiration_date
      in: query
      description: |
        Resource expiration date filter. Available filters are [eq, lt, lte, gt, gte]. Format according to ISO 8601
      required: false
      style: deepObject
      explode: true
      schema:
        $ref: '#/components/schemas/DateFilterEnum'
      example: 2023-01-05T03:30:15Z

    CataloguePromotionIdQueryParam:
      name: catalogue_promotion_id
      in: query
      description: Catalogue promotion identifier
      required: false
      schema:
        type: string
      example: "124"

    MsisdnQueryParam:
      name: msisdn
      in: query
      description: |
        MSISDN (Mobile Station International Subscriber Directory Number) following E.164 format. Spanish country
        code is assumed if plus sign(+) is not included to indicate international format.
      required: false
      schema:
        type: string
      example: +34611223344

    ImsiQueryParam:
      name: imsi
      in: query
      description: IMSI (International Mobile Subscriber Identity)
      required: false
      schema:
        type: string
      example: "214040000000000"

    DeviceIdQueryParam:
      name: device_id
      in: query
      description: Insured device ID
      required: false
      schema:
        type: string
        format: uuid
      example: 123e4567-e89b-12d3-a456-426614174000

    LegacyDeviceIdQueryParam:
      name: legacy_device_id
      in: query
      description: Legacy Id of the insured device in MySim/Apollo storage
      required: false
      schema:
        type: integer
      example: 123456

    CommercialTransactionIdQueryParam:
      name: commercial_transaction_id
      in: query
      required: false
      schema:
        type: string
      description: Filter by commercial transaction identifier

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
