basePath: /v1beta1/partners
definitions:
  billing_errors.BaseError:
    properties:
      code:
        type: string
      error: {}
      msgPrefix:
        type: string
      status:
        type: integer
    type: object
  forms.BillsOtherName:
    properties:
      chargeName:
        example: Support Plan
        type: string
      credits:
        description: The total credits held by the organization in this bill. The
          value of this field is expressed in cents (100ths of one US Dollar).
        example: "0.00"
        type: string
      discounts:
        description: The total amount of discounts applied to this bill. The value
          of this field is expressed in cents (100ths of one US Dollar).
        example: "0.00"
        type: string
      runningTotal:
        description: The sum of services that the specified organization has consumed
          during this bill period. The value of this field is expressed in cents (100ths
          of one US Dollar).
        example: "0.00"
        type: string
      totalCost:
        description: |-
          The total amount that the specified organization should pay for this bill. The value of this field is expressed in cents (100ths of one US Dollar).
          `total_cost` = `running_total` - `discounts` - `credits`.
        example: "0.00"
        type: string
    type: object
  forms.BillsOverview:
    properties:
      billedMonth:
        description: The month in which this bill is generated for the specified organization.
        example: 2023-09
        type: string
      credits:
        description: The total credits held by the organization in this bill. The
          value of this field is expressed in cents (100ths of one US Dollar).
        example: "0.00"
        type: string
      discounts:
        description: The total amount of discounts applied to this bill. The value
          of this field is expressed in cents (100ths of one US Dollar).
        example: "0.00"
        type: string
      runningTotal:
        description: The sum of services that the specified organization has consumed
          during this bill period. The value of this field is expressed in cents (100ths
          of one US Dollar).
        example: "0.00"
        type: string
      totalCost:
        description: |-
          The total amount that the specified organization should pay for this bill. The value of this field is expressed in cents (100ths of one US Dollar).
          `total_cost` = `running_total` - `discounts` - `credits`.
        example: "0.00"
        type: string
    type: object
  forms.BillsProjects:
    properties:
      credits:
        description: The total credits held by the organization in this bill. The
          value of this field is expressed in cents (100ths of one US Dollar).
        example: "0.00"
        type: string
      discounts:
        description: The total amount of discounts applied to this bill. The value
          of this field is expressed in cents (100ths of one US Dollar).
        example: "0.00"
        type: string
      projectName:
        description: The name of a project in the specified organization.
        example: prod-project
        type: string
      runningTotal:
        description: The sum of services that the specified organization has consumed
          during this bill period. The value of this field is expressed in cents (100ths
          of one US Dollar).
        example: "0.00"
        type: string
      totalCost:
        description: |-
          The total amount that the specified organization should pay for this bill. The value of this field is expressed in cents (100ths of one US Dollar).
          `total_cost` = `running_total` - `discounts` - `credits`.
        example: "0.00"
        type: string
    type: object
  forms.BillsServiceCosts:
    properties:
      credits:
        description: The total credits held by the organization in this bill. The
          value of this field is expressed in cents (100ths of one US Dollar).
        example: "0.00"
        type: string
      discounts:
        description: The total amount of discounts applied to this bill. The value
          of this field is expressed in cents (100ths of one US Dollar).
        example: "0.00"
        type: string
      runningTotal:
        description: The sum of services that the specified organization has consumed
          during this bill period. The value of this field is expressed in cents (100ths
          of one US Dollar).
        example: "0.00"
        type: string
      serviceCosts:
        items:
          $ref: '#/definitions/forms.BillsServiceCosts'
        type: array
      serviceName:
        description: The name of services provided by TiDB Cloud.
        example: TiDB Dedicated
        type: string
      totalCost:
        description: |-
          The total amount that the specified organization should pay for this bill. The value of this field is expressed in cents (100ths of one US Dollar).
          `total_cost` = `running_total` - `discounts` - `credits`.
        example: "0.00"
        type: string
    type: object
  forms.CostExplorerProvider:
    properties:
      name:
        description: The name of the cloud provider to include in the query.
        type: string
      regions:
        description: A list of region names to include in the query.
        items:
          type: string
        type: array
    type: object
  forms.CostExplorerService:
    properties:
      category:
        description: The service category name (second level).
        type: string
      component:
        description: The service component name (third level).
        type: string
      product:
        description: The service product name (first level).
        type: string
      service:
        description: The full service name, typically combining all levels.
        type: string
    type: object
  forms.CostExplorerTrendsBreakdownKey:
    enum:
    - service
    - product
    - project
    - cluster
    - provider
    - region
    - customer
    type: string
    x-enum-varnames:
    - CostExploreTrendsBreakdownKeyService
    - CostExploreTrendsBreakdownKeyProduct
    - CostExploreTrendsBreakdownKeyProject
    - CostExploreTrendsBreakdownKeyCluster
    - CostExploreTrendsBreakdownKeyProvider
    - CostExploreTrendsBreakdownKeyRegion
    - CostExploreTrendsBreakdownKeyCustomer
  forms.CostExplorerTrendsTimeGroup:
    enum:
    - day
    - month
    - total
    type: string
    x-enum-varnames:
    - CostExploreTrendsTimeGroupDay
    - CostExploreTrendsTimeGroupMonth
    - CostExploreTrendsTimeGroupTotal
  forms.CustomerBills:
    properties:
      credits:
        description: The total credits held by the organization in this bill. The
          value of this field is expressed in cents (100ths of one US Dollar).
        example: "0.00"
        type: string
      customerName:
        description: The name of the customer.
        example: PingCAP
        type: string
      discounts:
        description: The total amount of discounts applied to this bill. The value
          of this field is expressed in cents (100ths of one US Dollar).
        example: "0.00"
        type: string
      runningTotal:
        description: The sum of services that the specified organization has consumed
          during this bill period. The value of this field is expressed in cents (100ths
          of one US Dollar).
        example: "0.00"
        type: string
      totalCost:
        description: |-
          The total amount that the specified organization should pay for this bill. The value of this field is expressed in cents (100ths of one US Dollar).
          `total_cost` = `running_total` - `discounts` - `credits`.
        example: "0.00"
        type: string
    type: object
  forms.Groups:
    properties:
      groupBy:
        description: |-
          Specifies categories for grouping query results. Value options are:
          - "service": Group query results by service type
          - "product": Group query results by product type (TiDB Dedicated, TiDB Serverless, or Support Plan)
          - "project": Group query results by project IDs
          - "cluster": Group query results by cluster IDs
          - "provider": Group query results by cloud provider
          - "region": Group query results by cloud provider region
        items:
          $ref: '#/definitions/forms.CostExplorerTrendsBreakdownKey'
        type: array
      timeGranularity:
        allOf:
        - $ref: '#/definitions/forms.CostExplorerTrendsTimeGroup'
        description: |-
          Determines the time-based organization of query results. Value options are:
          - "day": Query results are organized daily
          - "month": Query results are organized monthly
          - "total": Query results are organized as a single total
    type: object
  forms.PartnerBillsExplorer:
    properties:
      overview:
        allOf:
        - $ref: '#/definitions/forms.BillsOverview'
        description: The overall information for a bill in the specified organization.
      summaryByCustomer:
        allOf:
        - $ref: '#/definitions/forms.SummaryBillsByCustomer'
        description: A breakdown of the bill by customers.
      summaryByProject:
        allOf:
        - $ref: '#/definitions/forms.SummaryByProject'
        description: A breakdown of the bill by project.
      summaryByService:
        description: A breakdown of the bill by services.
        items:
          $ref: '#/definitions/forms.PartnerBillsServiceCosts'
        type: array
    type: object
  forms.PartnerBillsServiceCosts:
    properties:
      credits:
        description: The total credits held by the organization in this bill. The
          value of this field is expressed in cents (100ths of one US Dollar).
        example: "0.00"
        type: string
      discounts:
        description: The total amount of discounts applied to this bill. The value
          of this field is expressed in cents (100ths of one US Dollar).
        example: "0.00"
        type: string
      runningTotal:
        description: The sum of services that the specified organization has consumed
          during this bill period. The value of this field is expressed in cents (100ths
          of one US Dollar).
        example: "0.00"
        type: string
      serviceCosts:
        description: A breakdown of the bill by service.
        items:
          $ref: '#/definitions/forms.PartnerBillsServiceCosts'
        type: array
      serviceName:
        description: The name of services provided by TiDB Cloud.
        example: TiDB Dedicated
        type: string
      totalCost:
        description: |-
          The total amount that the specified organization should pay for this bill. The value of this field is expressed in cents (100ths of one US Dollar).
          `total_cost` = `running_total` - `discounts` - `credits`.
        example: "0.00"
        type: string
    type: object
  forms.PartnerInvoicedBillsDetail:
    properties:
      billedDate:
        description: The date when this bill happens.
        type: string
      clusterName:
        description: Name of the cluster.
        type: string
      credits:
        description: The total credits held by the organization in this bill. The
          value of this field is expressed in cents (100ths of one US Dollar).
        example: "0.00"
        type: string
      customerName:
        example: PingCAP
        type: string
      discounts:
        description: The total amount of discounts applied to this bill. The value
          of this field is expressed in cents (100ths of one US Dollar).
        example: "0.00"
        type: string
      invoicedDate:
        type: string
      paymentCode:
        type: string
      projectName:
        description: Name of the project.
        type: string
      runningTotal:
        description: The sum of services that the specified organization has consumed
          during this bill period. The value of this field is expressed in cents (100ths
          of one US Dollar).
        example: "0.00"
        type: string
      servicePathName:
        description: Name of the service.
        type: string
      totalCost:
        description: |-
          The total amount that the specified organization should pay for this bill. The value of this field is expressed in cents (100ths of one US Dollar).
          `total_cost` = `running_total` - `discounts` - `credits`.
        example: "0.00"
        type: string
    type: object
  forms.PartnerInvoicedBillsDetails:
    properties:
      details:
        items:
          $ref: '#/definitions/forms.PartnerInvoicedBillsDetail'
        type: array
    type: object
  forms.PartnerTrendsFilter:
    properties:
      clusters:
        description: A list of cluster IDs to include in the query.
        items:
          type: string
        type: array
      customers:
        items:
          type: string
        type: array
      projects:
        description: A list of project IDs to include in the query.
        items:
          type: string
        type: array
      providers:
        description: A list of providers to include in the query.
        items:
          $ref: '#/definitions/forms.CostExplorerProvider'
        type: array
      services:
        description: A list of TiDB Cloud services to include in the query.
        items:
          $ref: '#/definitions/forms.CostExplorerService'
        type: array
      timeRange:
        allOf:
        - $ref: '#/definitions/forms.TimeRange'
        description: The time period for the query.
    type: object
  forms.PartnerTrendsInput:
    properties:
      filter:
        $ref: '#/definitions/forms.PartnerTrendsFilter'
      groups:
        $ref: '#/definitions/forms.Groups'
    type: object
  forms.SummaryBillsByCustomer:
    properties:
      customers:
        description: The breakdown of bills by customers of a partner.
        items:
          $ref: '#/definitions/forms.CustomerBills'
        type: array
      otherCharges:
        description: Costs not incurred by the customer but by the partner, such as
          support plan for a MSP.
        items:
          $ref: '#/definitions/forms.BillsOtherName'
        type: array
    type: object
  forms.SummaryByProject:
    properties:
      otherCharges:
        description: These charges occur not only within a project but also across
          the entire organization.
        items:
          $ref: '#/definitions/forms.BillsOtherName'
        type: array
      projects:
        description: The projects in the specified organization.
        items:
          $ref: '#/definitions/forms.BillsProjects'
        type: array
    type: object
  forms.TimeRange:
    properties:
      endDate:
        description: 'The end date of the time range. The time format follows the
          [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard. For example:
          `"2023-12-01T00:00:00Z"`.'
        type: string
      startDate:
        description: 'The start date of the time range. The time format follows the
          [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard. For example:
          `"2023-12-01T00:00:00Z"`.'
        type: string
    type: object
host: us-west-2.prod.aws.tidbcloud.com
info:
  contact: {}
  description: This is a billing system server for TiDB Cloud Partners.
  title: Partner OPENAPI
  version: v1beta1
paths:
  /billsCostExplorer/export:
    post:
      consumes:
      - application/json
      description: |-
        This endpoint executes a cost explorer query and returns the usage details. Cost explorer query:
        1. Allow users to group costs by category
        2. Allow users to focus on a specific cost item by filter
        3. Allow users to query cost in the specific time range
      operationId: TCPN_GetPartnerTrendsCSV
      parameters:
      - description: org_id
        in: query
        name: accessOrgId
        required: true
        type: string
      - description: withDiscountsAndCredits
        in: query
        name: withDiscountsAndCredits
        required: true
        type: boolean
      - description: Query arguments
        in: body
        name: args
        required: true
        schema:
          $ref: '#/definitions/forms.PartnerTrendsInput'
      produces:
      - application/json
      - text/csv
      responses:
        "200":
          description: OK
          schema:
            items:
              format: int32
              type: integer
            type: array
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/billing_errors.BaseError'
      summary: Get the usage details according to a cost explorer query
      tags:
      - PartnerPrivateAPI
  /billsDetails/{billedMonth}/export:
    get:
      consumes:
      - application/json
      description: Export Usage CSV
      operationId: TCPN_ExportUsageCSV
      parameters:
      - description: org_id
        in: query
        name: accessOrgId
        required: true
        type: string
      - description: The month of this bill happens for the specified organization,
          in the format of `YYYY-MM`. For example `2024-08`.
        in: path
        name: billedMonth
        required: true
        type: string
      produces:
      - application/json
      - text/csv
      responses:
        "200":
          description: OK
          schema:
            items:
              format: int32
              type: integer
            type: array
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/billing_errors.BaseError'
      summary: Export Usage CSV
      tags:
      - PartnerPrivateAPI
  /invoicedBills/{billedMonth}:
    get:
      consumes:
      - application/json
      description: This endpoint retrieves the bill for the given month of a specific
        organization based on the invoice sent date. The bill is returned in JSON
        format.
      operationId: Billing_GetPartnerInvoicedBills
      parameters:
      - description: org_id
        in: query
        name: accessOrgId
        required: true
        type: string
      - description: The month for which to retrieve the bill, in the format of `YYYY-MM`.
          This refers to the month when invoices were sent.
        in: path
        name: billedMonth
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/forms.PartnerBillsExplorer'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/billing_errors.BaseError'
      summary: Get organization monthly bills based on invoice sent date
      tags:
      - PartnerPrivateAPI
  /invoicedBillsDetails/{billedMonth}:
    get:
      consumes:
      - application/json
      description: This endpoint retrieves the bill for the given month of a specific
        organization with daily usage details, based on the invoice sent date.
      operationId: Billing_GetPartnerInvoicedBillsDetails
      parameters:
      - description: org_id
        in: query
        name: accessOrgId
        required: true
        type: string
      - description: The month of this bill happens for the specified organization,
          in the format of `YYYY-MM`. This refers to the month when invoices were
          sent.
        in: path
        name: billedMonth
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/forms.PartnerInvoicedBillsDetails'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/billing_errors.BaseError'
      summary: Get the monthly bill of the organization with daily usage details based
        on invoice sent date
      tags:
      - PartnerPrivateAPI
  /invoicedBillsDetails/{billedMonth}/export:
    get:
      consumes:
      - application/json
      description: Export Usage CSV based on the invoice sent date.
      operationId: TCPN_ExportInvoicedUsageCSV
      parameters:
      - description: org_id
        in: query
        name: accessOrgId
        required: true
        type: string
      - description: The month of this bill happens for the specified organization,
          in the format of `YYYY-MM`. This refers to the month when invoices were
          sent.
        in: path
        name: billedMonth
        required: true
        type: string
      produces:
      - text/csv
      responses:
        "200":
          description: OK
          schema:
            items:
              format: int32
              type: integer
            type: array
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/billing_errors.BaseError'
      summary: Export Usage CSV based on invoice sent date
      tags:
      - PartnerPrivateAPI
  /swaggerDoc:
    get:
      consumes:
      - application/json
      description: Swagger Doc
      operationId: TCPN_SwaggerDoc
      parameters:
      - description: org_id
        in: query
        name: accessOrgId
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              format: int32
              type: integer
            type: array
      summary: Swagger Doc
      tags:
      - PartnerPrivateAPI
  /userManualDoc:
    get:
      consumes:
      - application/json
      description: User Manual
      operationId: TCPN_UserManual
      parameters:
      - description: org_id
        in: query
        name: accessOrgId
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              format: int32
              type: integer
            type: array
      summary: User Manual
      tags:
      - PartnerPrivateAPI
swagger: "2.0"