openapi: 3.1.0
info:
  title: Waste Management Customer Cases Services API
  description: The Waste Management Customer API provides RESTful access to customer account information including balance due, contract details, invoice history, service details, and pick-up status. The API uses JWT bearer token authentication and supports JSON and XML response formats. Endpoints are organized under the customer resource and cover activities, balance, cases, contacts, invoices, preferences, profiles, services, and tickets.
  version: '1.0'
  contact:
    name: Waste Management Developer Support
    url: https://api.wm.com/
servers:
- url: https://api.wm.com/v1
  description: Production
- url: https://apitest.wm.com/v1
  description: Test
tags:
- name: Services
  description: Retrieve service details, schedules, materials, and ETAs.
paths:
  /customers/{customerId}/services:
    get:
      operationId: listServices
      summary: List Services
      description: Retrieves detailed information on the services associated with the authenticated customer account, including service type, materials, equipment, and pricing.
      tags:
      - Services
      parameters:
      - $ref: '#/components/parameters/CustomerId'
      - $ref: '#/components/parameters/RequestTrackingId'
      - $ref: '#/components/parameters/ClientId'
      - name: line_of_business
        in: query
        description: Filter services by line of business.
        schema:
          type: string
          enum:
          - RESIDENTIAL
          - COMMERCIAL
          - ROLLOFF
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /customers/{customerId}/services/plan:
    get:
      operationId: listPlannedServices
      summary: List Planned Services
      description: Retrieves the status of services occurring today for commercial or residential customers.
      tags:
      - Services
      parameters:
      - $ref: '#/components/parameters/CustomerId'
      - $ref: '#/components/parameters/RequestTrackingId'
      - $ref: '#/components/parameters/ClientId'
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Success
        '401':
          $ref: '#/components/responses/Unauthorized'
  /customers/{customerId}/services/materials:
    get:
      operationId: listServiceMaterials
      summary: List Service Materials
      description: Retrieves hauling material information for all services associated with the customer account.
      tags:
      - Services
      parameters:
      - $ref: '#/components/parameters/CustomerId'
      - $ref: '#/components/parameters/RequestTrackingId'
      - $ref: '#/components/parameters/ClientId'
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Success
        '401':
          $ref: '#/components/responses/Unauthorized'
  /customers/{customerId}/services/prices/invoice-fees:
    get:
      operationId: listServiceInvoiceFees
      summary: List Service Invoice Fees
      description: Retrieves all invoice fees including fuel, environmental, and regulatory cost recovery fees for services.
      tags:
      - Services
      parameters:
      - $ref: '#/components/parameters/CustomerId'
      - $ref: '#/components/parameters/RequestTrackingId'
      - $ref: '#/components/parameters/ClientId'
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Success
        '401':
          $ref: '#/components/responses/Unauthorized'
  /customers/{customerId}/services/operations:
    get:
      operationId: listServiceOperations
      summary: List Service Operations
      description: Retrieves operational details for services associated with the customer account.
      tags:
      - Services
      parameters:
      - $ref: '#/components/parameters/CustomerId'
      - $ref: '#/components/parameters/RequestTrackingId'
      - $ref: '#/components/parameters/ClientId'
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Success
        '401':
          $ref: '#/components/responses/Unauthorized'
  /customers/{customerId}/services/next-pickup:
    get:
      operationId: getNextPickup
      summary: Get Next Pickup
      description: Retrieves upcoming pickup schedule information for the customer's waste and recycling services.
      tags:
      - Services
      parameters:
      - $ref: '#/components/parameters/CustomerId'
      - $ref: '#/components/parameters/RequestTrackingId'
      - $ref: '#/components/parameters/ClientId'
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Success
        '401':
          $ref: '#/components/responses/Unauthorized'
  /customers/{customerId}/services/{serviceId}/eta:
    get:
      operationId: getServiceEta
      summary: Get Service ETA
      description: Retrieves the estimated time of arrival (ETA) for a specific service, indicating when the service is expected or if it has already been completed.
      tags:
      - Services
      parameters:
      - $ref: '#/components/parameters/CustomerId'
      - name: serviceId
        in: path
        required: true
        description: The unique service identifier.
        schema:
          type: string
      - $ref: '#/components/parameters/RequestTrackingId'
      - $ref: '#/components/parameters/ClientId'
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Success
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    RequestTrackingId:
      name: Request-Tracking-Id
      in: header
      required: true
      description: A unique identifier for tracking each API request.
      schema:
        type: string
        format: uuid
    ClientId:
      name: ClientId
      in: header
      required: true
      description: Client identifier provided by Waste Management.
      schema:
        type: string
    CustomerId:
      name: customerId
      in: path
      required: true
      description: The unique WM customer identifier.
      schema:
        type: string
  responses:
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized — invalid or missing JWT token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ServicePricing:
      type: object
      description: Pricing information for a service.
      properties:
        monthlyBaseCost:
          type: number
          format: decimal
        currency:
          type: string
          default: USD
    ServiceMaterial:
      type: object
      description: Material information for a service.
      properties:
        materialCode:
          type: string
        materialName:
          type: string
        specialHandling:
          type: boolean
    ServiceList:
      type: object
      description: List of services associated with a WM customer account.
      properties:
        services:
          type: array
          items:
            $ref: '#/components/schemas/Service'
    ErrorResponse:
      type: object
      description: Standard error response from the WM API.
      properties:
        code:
          type: integer
          description: HTTP status code.
        message:
          type: string
          description: Human-readable error message.
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              description:
                type: string
    ServiceEquipment:
      type: object
      description: Equipment details for a service.
      properties:
        equipmentName:
          type: string
        volume:
          type: number
        unitOfMeasure:
          type: string
        containerCount:
          type: integer
    Service:
      type: object
      description: A WM service associated with a customer account.
      properties:
        serviceId:
          type: string
          description: Unique service identifier.
        status:
          type: string
          description: Current service status.
        occurrenceFrequency:
          type: string
          description: Service frequency (e.g., Weekly, Bi-Weekly).
        lineOfBusiness:
          type: string
          enum:
          - RESIDENTIAL
          - COMMERCIAL
          - ROLLOFF
          description: Line of business for this service.
        serviceName:
          type: string
          description: Human-readable service name.
        material:
          $ref: '#/components/schemas/ServiceMaterial'
        equipment:
          $ref: '#/components/schemas/ServiceEquipment'
        pricing:
          $ref: '#/components/schemas/ServicePricing'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JSON Web Token (JWT) provided by WM.