openapi: 3.1.0
info:
  title: Amdocs connectX BSS API
  description: >-
    The Amdocs connectX BSS API provides cloud-native SaaS BSS capabilities for
    telecom operators covering billing, provisioning, customer management, and
    subscription lifecycle. REST APIs enable integration with CRM, network management,
    and revenue assurance systems for digital telco operations.
  version: 1.0.0
  contact:
    name: Amdocs Developer Portal
    url: https://devportal.amdocs-dbs.com/

servers:
  - url: https://api.amdocs-dbs.com
    description: Amdocs connectX Production API

security:
  - oauth2: []

tags:
  - name: Billing
    description: Billing and invoice operations
  - name: Customers
    description: Customer account management
  - name: Products
    description: Product catalog management

  - name: Subscriptions
    description: Subscription lifecycle management
paths:
  /v1/customers:
    get:
      operationId: listCustomers
      summary: List customers
      description: Retrieve a paginated list of telecom customer accounts.
      tags: [Customers]
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [Active, Inactive, Suspended, Terminated]
        - name: customerType
          in: query
          schema:
            type: string
            enum: [Individual, Business, Government]
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 25
      responses:
        '200':
          description: List of customers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      operationId: createCustomer
      summary: Create a new customer
      description: Onboard a new telecom customer account into the BSS system.
      tags: [Customers]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerRequest'
      responses:
        '201':
          description: Customer created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'

  /v1/customers/{customerId}:
    get:
      operationId: getCustomer
      summary: Get customer by ID
      description: Retrieve full customer account details including contact info and account status.
      tags: [Customers]
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Customer details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      operationId: updateCustomer
      summary: Update customer
      description: Update customer account information such as contact details or account status.
      tags: [Customers]
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerUpdate'
      responses:
        '200':
          description: Customer updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'

  /v1/customers/{customerId}/subscriptions:
    get:
      operationId: listCustomerSubscriptions
      summary: List customer subscriptions
      description: Retrieve all service subscriptions associated with a customer account.
      tags: [Subscriptions]
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: string
        - name: status
          in: query
          schema:
            type: string
            enum: [Active, Suspended, Cancelled, Pending]
      responses:
        '200':
          description: Customer subscriptions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionList'

    post:
      operationId: createSubscription
      summary: Create subscription
      description: Add a new service subscription to a customer account.
      tags: [Subscriptions]
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionRequest'
      responses:
        '201':
          description: Subscription created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'

  /v1/customers/{customerId}/invoices:
    get:
      operationId: listCustomerInvoices
      summary: List customer invoices
      description: Retrieve billing invoices for a customer, with optional date range filtering.
      tags: [Billing]
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: string
        - name: fromDate
          in: query
          schema:
            type: string
            format: date
        - name: toDate
          in: query
          schema:
            type: string
            format: date
        - name: status
          in: query
          schema:
            type: string
            enum: [Open, Paid, Overdue, Cancelled]
      responses:
        '200':
          description: Customer invoices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceList'

  /v1/products:
    get:
      operationId: listProducts
      summary: List products
      description: Retrieve the product and service catalog available for subscription.
      tags: [Products]
      parameters:
        - name: productType
          in: query
          schema:
            type: string
            enum: [Mobile, Broadband, TV, Bundle, Addon]
        - name: status
          in: query
          schema:
            type: string
            enum: [Active, Discontinued]
      responses:
        '200':
          description: Product catalog
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductList'

components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.amdocs-dbs.com/oauth/token
          scopes:
            read:customers: Read customer data
            write:customers: Manage customers
            read:billing: Read billing data
            write:subscriptions: Manage subscriptions

  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  schemas:
    Customer:
      type: object
      properties:
        customerId:
          type: string
        customerType:
          type: string
          enum: [Individual, Business, Government]
        status:
          type: string
          enum: [Active, Inactive, Suspended, Terminated]
        accountNumber:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        companyName:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
        address:
          $ref: '#/components/schemas/Address'
        billingAddress:
          $ref: '#/components/schemas/Address'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    CustomerRequest:
      type: object
      required: [customerType, email]
      properties:
        customerType:
          type: string
          enum: [Individual, Business, Government]
        firstName:
          type: string
        lastName:
          type: string
        companyName:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
        address:
          $ref: '#/components/schemas/Address'

    CustomerUpdate:
      type: object
      properties:
        status:
          type: string
          enum: [Active, Inactive, Suspended]
        email:
          type: string
          format: email
        phone:
          type: string
        address:
          $ref: '#/components/schemas/Address'

    CustomerList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Customer'
        pagination:
          $ref: '#/components/schemas/Pagination'

    Subscription:
      type: object
      properties:
        subscriptionId:
          type: string
        customerId:
          type: string
        productId:
          type: string
        productName:
          type: string
        status:
          type: string
          enum: [Active, Suspended, Cancelled, Pending]
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
        monthlyCharge:
          type: number
        currency:
          type: string
          default: USD
        addons:
          type: array
          items:
            type: object
            properties:
              addonId:
                type: string
              addonName:
                type: string
              charge:
                type: number

    SubscriptionRequest:
      type: object
      required: [productId, startDate]
      properties:
        productId:
          type: string
        startDate:
          type: string
          format: date
        addons:
          type: array
          items:
            type: string

    SubscriptionList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Subscription'

    Invoice:
      type: object
      properties:
        invoiceId:
          type: string
        invoiceNumber:
          type: string
        customerId:
          type: string
        status:
          type: string
          enum: [Open, Paid, Overdue, Cancelled]
        invoiceDate:
          type: string
          format: date
        dueDate:
          type: string
          format: date
        totalAmount:
          type: number
        taxAmount:
          type: number
        currency:
          type: string
        lineItems:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceLineItem'

    InvoiceLineItem:
      type: object
      properties:
        description:
          type: string
        quantity:
          type: number
        unitPrice:
          type: number
        amount:
          type: number

    InvoiceList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Invoice'
        pagination:
          $ref: '#/components/schemas/Pagination'

    Product:
      type: object
      properties:
        productId:
          type: string
        productName:
          type: string
        productType:
          type: string
          enum: [Mobile, Broadband, TV, Bundle, Addon]
        description:
          type: string
        monthlyPrice:
          type: number
        currency:
          type: string
        features:
          type: array
          items:
            type: string
        status:
          type: string
          enum: [Active, Discontinued]

    ProductList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Product'

    Address:
      type: object
      properties:
        street:
          type: string
        city:
          type: string
        state:
          type: string
        postalCode:
          type: string
        country:
          type: string

    Pagination:
      type: object
      properties:
        page:
          type: integer
        pageSize:
          type: integer
        totalPages:
          type: integer
        totalItems:
          type: integer

    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string