{ "swagger": "2.0", "info": { "description": "This is a billing system server for TiDB Cloud Partners.", "title": "Partner OPENAPI", "contact": {}, "version": "v1beta1" }, "host": "us-west-2.prod.aws.tidbcloud.com", "basePath": "/v1beta1/partners", "paths": { "/billsCostExplorer/export": { "post": { "description": "This endpoint executes a cost explorer query and returns the usage details. Cost explorer query:\n1. Allow users to group costs by category\n2. Allow users to focus on a specific cost item by filter\n3. Allow users to query cost in the specific time range", "consumes": [ "application/json" ], "produces": [ "application/json", "text/csv" ], "tags": [ "PartnerPrivateAPI" ], "summary": "Get the usage details according to a cost explorer query", "operationId": "TCPN_GetPartnerTrendsCSV", "parameters": [ { "type": "string", "description": "org_id", "name": "accessOrgId", "in": "query", "required": true }, { "type": "boolean", "description": "withDiscountsAndCredits", "name": "withDiscountsAndCredits", "in": "query", "required": true }, { "description": "Query arguments", "name": "args", "in": "body", "required": true, "schema": { "$ref": "#/definitions/forms.PartnerTrendsInput" } } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "type": "integer", "format": "int32" } } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/billing_errors.BaseError" } } } } }, "/billsDetails/{billedMonth}/export": { "get": { "description": "Export Usage CSV", "consumes": [ "application/json" ], "produces": [ "application/json", "text/csv" ], "tags": [ "PartnerPrivateAPI" ], "summary": "Export Usage CSV", "operationId": "TCPN_ExportUsageCSV", "parameters": [ { "type": "string", "description": "org_id", "name": "accessOrgId", "in": "query", "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`.", "name": "billedMonth", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "type": "integer", "format": "int32" } } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/billing_errors.BaseError" } } } } }, "/invoicedBills/{billedMonth}": { "get": { "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.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "PartnerPrivateAPI" ], "summary": "Get organization monthly bills based on invoice sent date", "operationId": "Billing_GetPartnerInvoicedBills", "parameters": [ { "type": "string", "description": "org_id", "name": "accessOrgId", "in": "query", "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.", "name": "billedMonth", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/forms.PartnerBillsExplorer" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/billing_errors.BaseError" } } } } }, "/invoicedBillsDetails/{billedMonth}": { "get": { "description": "This endpoint retrieves the bill for the given month of a specific organization with daily usage details, based on the invoice sent date.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "PartnerPrivateAPI" ], "summary": "Get the monthly bill of the organization with daily usage details based on invoice sent date", "operationId": "Billing_GetPartnerInvoicedBillsDetails", "parameters": [ { "type": "string", "description": "org_id", "name": "accessOrgId", "in": "query", "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.", "name": "billedMonth", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/forms.PartnerInvoicedBillsDetails" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/billing_errors.BaseError" } } } } }, "/invoicedBillsDetails/{billedMonth}/export": { "get": { "description": "Export Usage CSV based on the invoice sent date.", "consumes": [ "application/json" ], "produces": [ "text/csv" ], "tags": [ "PartnerPrivateAPI" ], "summary": "Export Usage CSV based on invoice sent date", "operationId": "TCPN_ExportInvoicedUsageCSV", "parameters": [ { "type": "string", "description": "org_id", "name": "accessOrgId", "in": "query", "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.", "name": "billedMonth", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "type": "integer", "format": "int32" } } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/billing_errors.BaseError" } } } } }, "/swaggerDoc": { "get": { "description": "Swagger Doc", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "PartnerPrivateAPI" ], "summary": "Swagger Doc", "operationId": "TCPN_SwaggerDoc", "parameters": [ { "type": "string", "description": "org_id", "name": "accessOrgId", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "type": "integer", "format": "int32" } } } } } }, "/userManualDoc": { "get": { "description": "User Manual", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "PartnerPrivateAPI" ], "summary": "User Manual", "operationId": "TCPN_UserManual", "parameters": [ { "type": "string", "description": "org_id", "name": "accessOrgId", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "type": "integer", "format": "int32" } } } } } } }, "definitions": { "billing_errors.BaseError": { "type": "object", "properties": { "code": { "type": "string" }, "error": {}, "msgPrefix": { "type": "string" }, "status": { "type": "integer" } } }, "forms.BillsOtherName": { "type": "object", "properties": { "chargeName": { "type": "string", "example": "Support Plan" }, "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).", "type": "string", "example": "0.00" }, "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).", "type": "string", "example": "0.00" }, "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).", "type": "string", "example": "0.00" }, "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).\n`total_cost` = `running_total` - `discounts` - `credits`.", "type": "string", "example": "0.00" } } }, "forms.BillsOverview": { "type": "object", "properties": { "billedMonth": { "description": "The month in which this bill is generated for the specified organization.", "type": "string", "example": "2023-09" }, "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).", "type": "string", "example": "0.00" }, "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).", "type": "string", "example": "0.00" }, "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).", "type": "string", "example": "0.00" }, "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).\n`total_cost` = `running_total` - `discounts` - `credits`.", "type": "string", "example": "0.00" } } }, "forms.BillsProjects": { "type": "object", "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).", "type": "string", "example": "0.00" }, "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).", "type": "string", "example": "0.00" }, "projectName": { "description": "The name of a project in the specified organization.", "type": "string", "example": "prod-project" }, "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).", "type": "string", "example": "0.00" }, "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).\n`total_cost` = `running_total` - `discounts` - `credits`.", "type": "string", "example": "0.00" } } }, "forms.BillsServiceCosts": { "type": "object", "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).", "type": "string", "example": "0.00" }, "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).", "type": "string", "example": "0.00" }, "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).", "type": "string", "example": "0.00" }, "serviceCosts": { "type": "array", "items": { "$ref": "#/definitions/forms.BillsServiceCosts" } }, "serviceName": { "description": "The name of services provided by TiDB Cloud.", "type": "string", "example": "TiDB Dedicated" }, "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).\n`total_cost` = `running_total` - `discounts` - `credits`.", "type": "string", "example": "0.00" } } }, "forms.CostExplorerProvider": { "type": "object", "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.", "type": "array", "items": { "type": "string" } } } }, "forms.CostExplorerService": { "type": "object", "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" } } }, "forms.CostExplorerTrendsBreakdownKey": { "type": "string", "enum": [ "service", "product", "project", "cluster", "provider", "region", "customer" ], "x-enum-varnames": [ "CostExploreTrendsBreakdownKeyService", "CostExploreTrendsBreakdownKeyProduct", "CostExploreTrendsBreakdownKeyProject", "CostExploreTrendsBreakdownKeyCluster", "CostExploreTrendsBreakdownKeyProvider", "CostExploreTrendsBreakdownKeyRegion", "CostExploreTrendsBreakdownKeyCustomer" ] }, "forms.CostExplorerTrendsTimeGroup": { "type": "string", "enum": [ "day", "month", "total" ], "x-enum-varnames": [ "CostExploreTrendsTimeGroupDay", "CostExploreTrendsTimeGroupMonth", "CostExploreTrendsTimeGroupTotal" ] }, "forms.CustomerBills": { "type": "object", "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).", "type": "string", "example": "0.00" }, "customerName": { "description": "The name of the customer.", "type": "string", "example": "PingCAP" }, "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).", "type": "string", "example": "0.00" }, "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).", "type": "string", "example": "0.00" }, "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).\n`total_cost` = `running_total` - `discounts` - `credits`.", "type": "string", "example": "0.00" } } }, "forms.Groups": { "type": "object", "properties": { "groupBy": { "description": "Specifies categories for grouping query results. Value options are:\n- \"service\": Group query results by service type\n- \"product\": Group query results by product type (TiDB Dedicated, TiDB Serverless, or Support Plan)\n- \"project\": Group query results by project IDs\n- \"cluster\": Group query results by cluster IDs\n- \"provider\": Group query results by cloud provider\n- \"region\": Group query results by cloud provider region", "type": "array", "items": { "$ref": "#/definitions/forms.CostExplorerTrendsBreakdownKey" } }, "timeGranularity": { "description": "Determines the time-based organization of query results. Value options are:\n- \"day\": Query results are organized daily\n- \"month\": Query results are organized monthly\n- \"total\": Query results are organized as a single total", "allOf": [ { "$ref": "#/definitions/forms.CostExplorerTrendsTimeGroup" } ] } } }, "forms.PartnerBillsExplorer": { "type": "object", "properties": { "overview": { "description": "The overall information for a bill in the specified organization.", "allOf": [ { "$ref": "#/definitions/forms.BillsOverview" } ] }, "summaryByCustomer": { "description": "A breakdown of the bill by customers.", "allOf": [ { "$ref": "#/definitions/forms.SummaryBillsByCustomer" } ] }, "summaryByProject": { "description": "A breakdown of the bill by project.", "allOf": [ { "$ref": "#/definitions/forms.SummaryByProject" } ] }, "summaryByService": { "description": "A breakdown of the bill by services.", "type": "array", "items": { "$ref": "#/definitions/forms.PartnerBillsServiceCosts" } } } }, "forms.PartnerBillsServiceCosts": { "type": "object", "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).", "type": "string", "example": "0.00" }, "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).", "type": "string", "example": "0.00" }, "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).", "type": "string", "example": "0.00" }, "serviceCosts": { "description": "A breakdown of the bill by service.", "type": "array", "items": { "$ref": "#/definitions/forms.PartnerBillsServiceCosts" } }, "serviceName": { "description": "The name of services provided by TiDB Cloud.", "type": "string", "example": "TiDB Dedicated" }, "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).\n`total_cost` = `running_total` - `discounts` - `credits`.", "type": "string", "example": "0.00" } } }, "forms.PartnerInvoicedBillsDetail": { "type": "object", "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).", "type": "string", "example": "0.00" }, "customerName": { "type": "string", "example": "PingCAP" }, "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).", "type": "string", "example": "0.00" }, "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).", "type": "string", "example": "0.00" }, "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).\n`total_cost` = `running_total` - `discounts` - `credits`.", "type": "string", "example": "0.00" } } }, "forms.PartnerInvoicedBillsDetails": { "type": "object", "properties": { "details": { "type": "array", "items": { "$ref": "#/definitions/forms.PartnerInvoicedBillsDetail" } } } }, "forms.PartnerTrendsFilter": { "type": "object", "properties": { "clusters": { "description": "A list of cluster IDs to include in the query.", "type": "array", "items": { "type": "string" } }, "customers": { "type": "array", "items": { "type": "string" } }, "projects": { "description": "A list of project IDs to include in the query.", "type": "array", "items": { "type": "string" } }, "providers": { "description": "A list of providers to include in the query.", "type": "array", "items": { "$ref": "#/definitions/forms.CostExplorerProvider" } }, "services": { "description": "A list of TiDB Cloud services to include in the query.", "type": "array", "items": { "$ref": "#/definitions/forms.CostExplorerService" } }, "timeRange": { "description": "The time period for the query.", "allOf": [ { "$ref": "#/definitions/forms.TimeRange" } ] } } }, "forms.PartnerTrendsInput": { "type": "object", "properties": { "filter": { "$ref": "#/definitions/forms.PartnerTrendsFilter" }, "groups": { "$ref": "#/definitions/forms.Groups" } } }, "forms.SummaryBillsByCustomer": { "type": "object", "properties": { "customers": { "description": "The breakdown of bills by customers of a partner.", "type": "array", "items": { "$ref": "#/definitions/forms.CustomerBills" } }, "otherCharges": { "description": "Costs not incurred by the customer but by the partner, such as support plan for a MSP.", "type": "array", "items": { "$ref": "#/definitions/forms.BillsOtherName" } } } }, "forms.SummaryByProject": { "type": "object", "properties": { "otherCharges": { "description": "These charges occur not only within a project but also across the entire organization.", "type": "array", "items": { "$ref": "#/definitions/forms.BillsOtherName" } }, "projects": { "description": "The projects in the specified organization.", "type": "array", "items": { "$ref": "#/definitions/forms.BillsProjects" } } } }, "forms.TimeRange": { "type": "object", "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" } } } } }