openapi: 3.2.0
info:
  title: DoiT Contracts API
  description: Programmatic access to DoiT Platform
  version: v1
servers:
- url: https://api.doit.com
security:
- api_key: []
- tenantId: []
  api_key: []
tags:
- name: Contracts
  description: List and manage tenant-scoped contracts as a T1/T2 PartnerOps caller.
paths:
  /customers/{customerID}/contracts:
    get:
      tags:
      - Contracts
      summary: List contracts
      description: Lists the contracts held by the specified customer. Callable by a T1/T2 PartnerOps principal for its own tenant or any descendant tenant. Read access requires contractsReadOnly, contractsViewer, or a write-capable role (without contractsReadOnly). User API tokens must include the matching permission in their scope.
      operationId: listContracts
      parameters:
      - name: customerID
        in: path
        description: The customer (tenant) whose contracts are requested.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK - The request succeeded.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MTSContractResponse'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
    post:
      tags:
      - Contracts
      summary: Create contract
      description: Creates a draft contract for the specified customer. Requires the caller to be the direct parent (T1 for a T2-level contract, T2 for a T3-level contract). Write access requires a role without contractsReadOnly; user API tokens must include the matching permission in their scope.
      operationId: createContract
      parameters:
      - name: customerID
        in: path
        description: The customer (tenant) the contract is created for.
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MTSContractInput'
      responses:
        '201':
          description: Created - The contract draft was created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateContractResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
  /customers/{customerID}/contracts/{contractID}:
    get:
      tags:
      - Contracts
      summary: Retrieve a contract
      description: Returns the specified contract.
      operationId: getContract
      parameters:
      - name: customerID
        in: path
        required: true
        schema:
          type: string
      - name: contractID
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK - Contract returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MTSContractDetailResponse'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
    post:
      tags:
      - Contracts
      summary: Update contract
      description: Creates a new version of the contract. The contract type is immutable and cannot be changed by an update.
      operationId: updateContract
      parameters:
      - name: customerID
        in: path
        required: true
        schema:
          type: string
      - name: contractID
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MTSContractInput'
      responses:
        '200':
          description: OK - New contract version created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateContractResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
  /customers/{customerID}/contracts/{contractID}/activate:
    post:
      tags:
      - Contracts
      summary: Activate contract
      description: Transitions a draft contract to active or scheduled (when the start date is in the future). Produces the same system state as activating via the Console.
      operationId: activateContract
      parameters:
      - name: customerID
        in: path
        required: true
        schema:
          type: string
      - name: contractID
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK - Contract activated or scheduled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractLifecycleResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          description: Conflict - An active contract of the same type already exists for this tier.
  /customers/{customerID}/contracts/{contractID}/cancel:
    post:
      tags:
      - Contracts
      summary: Cancel contract
      description: Cancels (deactivates) a contract. Active contracts cannot be deleted; cancel is the terminal operation.
      operationId: cancelContract
      parameters:
      - name: customerID
        in: path
        required: true
        schema:
          type: string
      - name: contractID
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  description: Optional cancellation reason.
      responses:
        '200':
          description: OK - Contract cancelled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractLifecycleResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
components:
  responses:
    '400':
      description: Bad Request - The server cannot process the request, often due to a malformed request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '401':
      description: Unauthorized - Invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '404':
      description: Not Found - The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '403':
      description: Forbidden - The client is not authorized to perform the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    MTSContractInput:
      type: object
      description: Contract create/update payload. Full field-level validation is applied server-side.
      required:
      - name
      - startDate
      - renewalPolicy
      - invoicesEmail
      - contractUpdatesEmail
      - billingProfile
      properties:
        name:
          type: string
        startDate:
          type: string
          format: date-time
        endDate:
          type:
          - string
          - 'null'
          format: date-time
        renewalPolicy:
          type: string
          enum:
          - auto
          - manual
          - fixed
        invoicesEmail:
          type: string
          format: email
        contractUpdatesEmail:
          type: string
          format: email
        billingProfile:
          type: object
          description: The billing profile (name, country, state, city, address, zip).
        managementAccounts:
          type: array
          items:
            type: string
        billingRules:
          type: array
          items:
            type: object
        priceBooks:
          type: array
          items:
            type: object
        customLineItems:
          type: array
          items:
            type: object
    ContractLifecycleResponse:
      type: object
      description: Result of an activate or cancel operation.
      properties:
        contractId:
          type: string
          description: The contract identifier.
        status:
          type: string
          description: The contract status after the operation (`active`, `scheduled`, or `cancelled`).
          enum:
          - active
          - scheduled
          - cancelled
    MTSContractDetailResponse:
      description: A single contract with its version terms. DoiT-internal fields are not exposed.
      allOf:
      - $ref: '#/components/schemas/MTSContractResponse'
      - type: object
        properties:
          versions:
            type: array
            description: The contract versions, newest last, with their billing terms.
            items:
              type: object
              properties:
                version:
                  type: integer
                  description: Contract version number.
                status:
                  type: string
                  description: Version status.
                name:
                  type: string
                startDate:
                  type: string
                  format: date-time
                endDate:
                  type:
                  - string
                  - 'null'
                  format: date-time
                effectiveStart:
                  type: string
                  format: date-time
                effectiveEnd:
                  type:
                  - string
                  - 'null'
                  format: date-time
                renewalPolicy:
                  type: string
                cancellationReason:
                  type:
                  - string
                  - 'null'
                billingProfile:
                  type: object
                invoicesEmail:
                  type: string
                  format: email
                contractUpdatesEmail:
                  type: string
                  format: email
                managementAccounts:
                  type: array
                  items:
                    type: string
                billingRules:
                  type: array
                  items:
                    type: object
                priceBooks:
                  type: array
                  items:
                    type: object
                customLineItems:
                  type: array
                  items:
                    type: object
    Error:
      type: object
      description: Standard error response structure.
      properties:
        error:
          type: string
          description: Detailed error message.
    CreateContractResponse:
      type: object
      description: The result of creating a contract or contract version.
      properties:
        contractId:
          type: string
        version:
          type: integer
        status:
          type: string
        message:
          type: string
        timestamp:
          type: string
          format: date-time
    MTSContractResponse:
      type: object
      description: External view of a contract. DoiT-internal fields are not exposed.
      properties:
        id:
          type: string
          description: The unique identifier of the contract.
        customerId:
          type: string
          description: The customer (tenant) that holds the contract.
        type:
          type: string
          description: The immutable contract type.
        status:
          type: string
          description: The contract status.
          enum:
          - draft
          - scheduled
          - active
          - cancelled
          - expired
          - superseded
        name:
          type: string
          description: The contract name.
        startDate:
          type:
          - string
          - 'null'
          format: date-time
          description: The contract start date.
        endDate:
          type:
          - string
          - 'null'
          format: date-time
          description: The contract end date.
        renewalPolicy:
          type: string
          description: The renewal policy.
          enum:
          - auto
          - manual
          - fixed
        currentVersionNumber:
          type:
          - integer
          - 'null'
          description: The current version number of the contract.
        timeCreated:
          type: string
          format: date-time
          description: When the contract was created.
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      description: Use the "Bearer <API_KEY>" format or sign in for autofill
      in: header
    tenantId:
      type: apiKey
      name: X-Tenant-Id
      description: 'Tenant (customer) ID that sets the request''s customer context.


        Required when the credential can access more than one tenant; omit when the

        credential is scoped to exactly one tenant (the server resolves that tenant

        automatically). If omitted for a multi-tenant credential, the request fails

        with `400` and code `tenant_id_required`. If the value conflicts with the

        credential''s tenant scope, the request fails with `400` and code

        `tenant_id_mismatch`.


        Use this header over the legacy `customerContext` query parameter, which

        only applies to legacy API keys and is ignored by personal and service-account

        API tokens.

        '
      in: header
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://console.doit.com/sign-in/oauth
          tokenUrl: https://console.doit.com/api/auth/token
          scopes:
            dci: Access All Data
x-samples-languages:
- curl
- go
- node
- python
x-cli-config:
  security: oauth2
  params:
    client_id: cli