{ "openapi": "3.0.0", "info": { "description": "## Introduction\n\nIn an IBM Cloud® enterprise, the billing unit manages all billing-related objects. With the Enterprise Billing Unit API, you can manage billing units, billing options, and credit pools for an enterprise. For more information about enterprise billing, see [Centrally managing billing and usage with enterprises](https://cloud.ibm.com/docs/enterprise-management?topic=enterprise-management-enterprise&interface=ui).\n\nSDKs for Java, Node, Python, and Go are available to make it easier to programmatically access the API from your code. The client libraries that are provided by the SDKs implement best practices for using the API and reduce the amount of code that you need to write. The tab for each language includes code examples that demonstrate how to use the client libraries. For more information about using the SDKs, see the [IBM Cloud SDK Common project](https://github.com/IBM/ibm-cloud-sdk-common) on GitHub.\n\nInstalling the Java SDK\n\nMaven\n\n```xml\n\n\tcom.ibm.cloud\n\tenterprise-billing-units\n\t{version}\n\n```\n\nGradle\n\n```bash\ncompile 'com.ibm.cloud:enterprise-billing-units:{version}'\n```\n\nReplace `{version}` in these examples with the release version.\n\nView on GitHub\n\n[https://github.com/IBM/platform-services-java-sdk](https://github.com/IBM/platform-services-java-sdk)\n\nInstalling the Node SDK\n\n```bash\nnpm install ibm-platform-services\n```\n\nView on GitHub\n\n[https://github.com/IBM/platform-services-node-sdk](https://github.com/IBM/platform-services-node-sdk)\n\nInstalling the Python SDK\n\npip\n\n```bash\npip install --upgrade \"ibm-platform-services\"\n```\n\nView on GitHub\n\n[https://github.com/IBM/platform-services-python-sdk](https://github.com/IBM/platform-services-python-sdk)\n\nInstalling the Go SDK\n\nGo modules (recommended): Add the following import in your code, and then run `go build` or `go mod tidy`\n\n```go\nimport (\n\t\"github.com/IBM/platform-services-go-sdk/enterprisebillingunitsv1\"\n)\n```\n\nGo get\n\n```bash\ngo get -u github.com/IBM/platform-services-go-sdk/enterprisebillingunitsv1\n```\n\nView on GitHub\n\n[https://github.com/IBM/platform-services-go-sdk](https://github.com/IBM/platform-services-go-sdk)\n\n## Endpoint URLs\n\nThe Enterprise Billing Units API uses the following global endpoint URL. When you call the API, add the path for each method to form the complete API endpoint for your requests.\n\n```\nhttps://billing.cloud.ibm.com\n```\n\nIf you enabled service endpoints in your account, you can send API requests over the IBM Cloud private network at the following base endpoint URLs. For more information, see [Enabling VRF and service endpoints](https://cloud.ibm.com/docs/account?topic=account-vrf-service-endpoint).\n\n* Private endpoint URL for VPC infrastructure: `https://private.billing.cloud.ibm.com`\n* Private endpoint URL (Dallas) for classic infrastructure: `https://private.us-south.billing.cloud.ibm.com`\n\nExample API request\n\n```sh\ncurl --request POST \\\n--header \"content-type: application/json\" \\\n--header \"accept: application/json\" \\\n--header \"authorization: Bearer \" \\\n--data \"{\\\"query\\\":\\\"string\\\"}\" \\\n--url \"https://api.billing.cloud.ibm.com/v1/resources/billing-options\n```\n\nReplace `` in this example with the value for your particular API call.\n\n## Authentication\n\nAuthorization to the Enterprise Billing Units API is enforced by using an IBM Cloud Identity and Access Management (IAM) access token. The token is used to determine the actions that a user or service ID has access to when they use the API.\n\nObtaining an IAM token for an authenticated user or service ID is described in the [IAM Identity Services API](https://cloud.ibm.com/docs/apis/iam-identity-token-api) documentation.\n\nTo use the API, add a valid IAM token to the HTTP Authorization request header, for example, `-H 'Authorization: Bearer '`.\n\nWhen you use the SDK, configure an IAM authenticator with the IAM API key. The authenticator automatically obtains the IAM access token for the API key and includes it with each request. You can construct an authenticator in either of two ways:\n- Programmatically by constructing an IAM authenticator instance and supplying your IAM API key\n- By defining the API key in external configuration properties and then using the SDK authenticator factory to construct an IAM authenticator that uses the configured IAM API key\n\nIn this example of using external configuration properties, an IAM authenticator instance is created with the configured API key, and then the service client is constructed with this authenticator instance and the configured service URL.\n\nFor more information, see the Authentication section of the [IBM Cloud SDK Common](https://github.com/IBM/ibm-cloud-sdk-common/blob/main/README.md) documentation.\n\nTo call each method, you'll need to be assigned a role that includes the required IAM actions. Each method lists the associated action. For more information about IAM actions and how they map to roles, see [Assigning access to account management services](https://cloud.ibm.com/docs/iam?topic=iam-account-services).\n\nTo retrieve your access token:\n\n```bash\ncurl -X POST \\\n \"https://iam.cloud.ibm.com/identity/token\" \\\n --header 'Content-Type: application/x-www-form-urlencoded' \\\n --header 'Accept: application/json' \\\n --data-urlencode 'grant_type=urn:ibm:params:oauth:grant-type:apikey' \\\n --data-urlencode 'apikey='\n```\n\nReplace `` with your IAM API key.\n\nSetting client options through external configuration\n\nExample environment variables, where `` is the endpoint URL and `` is your IAM API key\n```sh\nexport ENTERPRISE_BILLING_UNITS_URL=\nexport ENTERPRISE_BILLING_UNITS_AUTHTYPE=iam\nexport ENTERPRISE_BILLING_UNITS_APIKEY=\n```\n\nExample of constructing the service client\n```go\nimport {\n \"github.com/IBM/platform-services-go-sdk/enterprisebillingunitsv1\"\n}\n...\nserviceClientOptions := &enterprisebillingunitsv1.EnterpriseBillingUnitsV1Options{}\nserviceClient, err := enterprisebillingunitsv1.NewEnterpriseBillingUnitsV1UsingExternalConfig(serviceClientOptions)\n```\n\nSetting client options through external configuration\n\nExample environment variables, where `` is the endpoint URL and `` is your IAM API key\n```sh\nexport ENTERPRISE_BILLING_UNITS_URL=\nexport ENTERPRISE_BILLING_UNITS_AUTHTYPE=iam\nexport ENTERPRISE_BILLING_UNITS_APIKEY=\n```\n\nExample of constructing the service client\n```java\nimport com.ibm.cloud.platform_services.enterprise_billing_units.v1.EnterpriseBillingUnits;\n...\nEnterpriseBillingUnits serviceClient = EnterpriseBillingUnits.newInstance();\n```\n\nSetting client options through external configuration\n\nExample environment variables, where `` is the endpoint URL and `` is your IAM API key\n```sh\nexport ENTERPRISE_BILLING_UNITS_URL=\nexport ENTERPRISE_BILLING_UNITS_AUTHTYPE=iam\nexport ENTERPRISE_BILLING_UNITS_APIKEY=\n```\n\nExample of constructing the service client\n```javascript\nconst EnterpriseBillingUnitsV1 = require('ibm-platform-services/enterprise-billing-units/v1');\n...\nconst serviceClient = EnterpriseBillingUnitsV1.newInstance();\n```\n\nSetting client options through external configuration\n\nExample environment variables, where `` is the endpoint URL and `` is your IAM API key\n```sh\nexport ENTERPRISE_BILLING_UNITS_URL=\nexport ENTERPRISE_BILLING_UNITS_AUTHTYPE=iam\nexport ENTERPRISE_BILLING_UNITS_APIKEY=\n```\n\nExample of constructing the service client\n```python\nfrom ibm_platform_services import EnterpriseBillingUnitsV1\n...\nservice_client = EnterpriseBillingUnitsV1.new_instance()\n```\n\n## Error handling\n\nThe resource manager uses standard HTTP response codes to indicate whether a method completed successfully. A `200` type response always indicates success. A `400` type response is a failure, and a `500` type response is an internal system error.\n\n| HTTP Code | Description | Recovery |\n|:----------|:----------------------|:---------------------------------------------------------------------------------------------------------------------------------------|\n| `200` | Success | The request was successful. |\n| `400` | Bad Request | The input parameters in the request are either incomplete or in the wrong format. Be sure to include all the required parameters in your request. Be sure to validate your request. |\n| `401` | Authentication Failed | You are not authorized to make this request, or the token that is provided in the `Authorization` header is invalid or expired. Verify that the token is correct. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions. |\n| `403` | Authorization Failed | The supplied authentication is not authorized to access '{namespace}'. |\n| `404` | Not Found | The required resource was not found. |\n| `412` | Precondition Failed | The server failed to resolve account ID by request header fields. |\n| `424` | Dependency Failure | The dependencies for the entity are not set up correctly. The dependencies must be correct before a report can be generated. |\n| `5xx` | Internal Server Error | *offering name* is currently unavailable. Your request could not be processed. Wait a few minutes and try again. |\n\n## Pagination\n\nSome API requests might return many results. To avoid performance issues, these results are returned one page at a time, with a limited number of results on each page. `GET` requests for the following resources use pagination:\n\n * `/v1/billing-units?:query`\n * `/v1/billing-options?:query`\n * `/v1/credit-pools?:query`\n\nThe `rows_count`, `next_url` and `resources` fields are included in the collection response. The `next_url` field gives the link to the next page of results.\nBy default, each page contains 100 items, which is also the maximum number of items per page. To specify a different number of items per page, use the `limit` query parameter.\nThe `rows_count` field indicates the number of resources that exist on the page.\n\n## Related APIs\n\nSee the following related APIs for managing IBM Cloud enterprises:\n\n* [Enterprise Management API](https://cloud.ibm.com/docs/apis/enterprise-apis/enterprise): Create and manage enterprises, account groups, and accounts.\n* [Enterprise Usage Reports API](https://cloud.ibm.com/docs/apis/enterprise-apis/resource-usage-reports): Get usage reports for an enterprise, account group, or account.", "version": "1.0.0", "title": "Enterprise Billing Units", "contact": { "name": "Vasudev Balasubramanian", "email": "vasudev.balasubramanian@ibm.com" }, "x-alternate-name": "Enterprise Billing Units", "x-codegen-config": { "java": { "apiPackage": "com.ibm.cloud.platform_services" }, "go": { "apiPackage": "github.com/IBM/platform-services-go-sdk", "improvedNameFormattingV2": true }, "python": { "apiPackage": "ibm_platform_services" } }, "x-github": "https://github.ibm.com/cloud-api-docs/enterprise", "x-github-issues": "https://github.ibm.com/cloud-api-docs/enterprise/issues/new", "x-last-updated": "2026-09-03" }, "security": [ { "IAM": [] } ], "servers": [ { "url": "https://billing.cloud.ibm.com", "description": "Production" }, { "url": "https://billing.test.cloud.ibm.com", "description": "Staging" } ], "tags": [ { "name": "Billing Units", "description": "Operations on billing units." }, { "name": "Billing Options", "description": "Operations on billing options." }, { "name": "Credit Pools", "description": "Operation on credit pools." } ], "paths": { "/v1/billing-units/{billing_unit_id}": { "parameters": [ { "name": "billing_unit_id", "in": "path", "required": true, "description": "The ID of the requested billing unit.", "schema": { "type": "string" } } ], "get": { "tags": [ "Billing Units" ], "operationId": "get_billing_unit", "summary": "Get billing unit by ID", "description": "Return the billing unit information if it exists.", "x-ibm-permissions": { "actions": [ { "name": "billing.billing-unit.read" } ] }, "responses": { "200": { "description": "Status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingUnit" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } }, "404": { "description": "Billing unit not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } }, "412": { "description": "Failure to resolve enterprise account ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } }, "500": { "description": "Unexpected errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } } }, "x-sdk-operations": { "request-examples": { "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "getBillingUnitOptions := enterpriseBillingUnitsService.NewGetBillingUnitOptions(\n", " billingUnitID,\n", ")\n", "\n", "billingUnit, response, err := enterpriseBillingUnitsService.GetBillingUnit(getBillingUnitOptions)\n", "if err != nil {\n", " panic(err)\n", "}\n", "b, _ := json.MarshalIndent(billingUnit, \"\", \" \")\n", "fmt.Println(string(b))" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "GetBillingUnitOptions getBillingUnitOptions = new GetBillingUnitOptions.Builder()\n", " .billingUnitId(billingUnitId)\n", " .build();\n", "\n", "Response response = service.getBillingUnit(getBillingUnitOptions).execute();\n", "BillingUnit billingUnit = response.getResult();\n", "\n", "System.out.println(billingUnit);" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const params = {\n", " billingUnitId: billingUnitId,\n", "};\n", "\n", "enterpriseBillingUnitsService.getBillingUnit(params)\n", " .then(res => {\n", " console.log(JSON.stringify(res.result, null, 2));\n", " })\n", " .catch(err => {\n", " console.warn(err)\n", " });" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "billing_unit = enterprise_billing_units_service.get_billing_unit(\n", " billing_unit_id=billing_unit_id).get_result()\n", "\n", "print(json.dumps(billing_unit, indent=2))" ] } ] } ] } } } }, "/v1/billing-units": { "get": { "tags": [ "Billing Units" ], "operationId": "list_billing_units", "summary": "List billing units", "description": "Return matching billing unit information if any exists. Omits internal properties and enterprise account ID from the billing unit.", "parameters": [ { "name": "account_id", "in": "query", "required": false, "description": "The enterprise account ID.", "schema": { "type": "string" } }, { "name": "enterprise_id", "in": "query", "required": false, "description": "The enterprise ID.", "schema": { "type": "string" } }, { "name": "account_group_id", "in": "query", "required": false, "description": "The account group ID.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Return results up to this limit. Valid values are between 0 and 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "start", "in": "query", "required": false, "description": "The pagination offset. This represents the index of the first returned result.", "schema": { "type": "string" } } ], "x-ibm-permissions": { "actions": [ { "name": "billing.billing-unit.read" } ] }, "responses": { "200": { "description": "Status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingUnitsList" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } }, "404": { "description": "Billing unit not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } }, "412": { "description": "Failure to resolve enterprise account ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } }, "500": { "description": "Unexpected errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } } }, "x-sdk-operations": { "request-examples": { "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "listBillingUnitsOptions := enterpriseBillingUnitsService.NewListBillingUnitsOptions()\n", "listBillingUnitsOptions.SetEnterpriseID(enterpriseID)\n", "\n", "billingUnitsList, response, err := enterpriseBillingUnitsService.ListBillingUnits(listBillingUnitsOptions)\n", "if err != nil {\n", " panic(err)\n", "}\n", "b, _ := json.MarshalIndent(billingUnitsList, \"\", \" \")\n", "fmt.Println(string(b))" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "ListBillingUnitsOptions listBillingUnitsOptions = new ListBillingUnitsOptions.Builder()\n", " .enterpriseId(enterpriseId)\n", " .build();\n", "\n", "Response response = service.listBillingUnits(listBillingUnitsOptions).execute();\n", "BillingUnitsList billingUnitsList = response.getResult();\n", "\n", "System.out.println(billingUnitsList);" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const params = {\n", " enterpriseId: enterpriseId,\n", "};\n", "enterpriseBillingUnitsService.listBillingUnits(params)\n", " .then(res => {\n", " console.log(JSON.stringify(res.result, null, 2));\n", " })\n", " .catch(err => {\n", " console.warn(err)\n", " });" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "billing_units_list = enterprise_billing_units_service.list_billing_units(\n", " enterprise_id=enterprise_id).get_result()\n", "\n", "print(json.dumps(billing_units_list, indent=2))" ] } ] } ] } } } }, "/v1/billing-options": { "get": { "tags": [ "Billing Options" ], "operationId": "list_billing_options", "summary": "List billing options", "description": "Return matching billing options if any exist. Show subscriptions and promotional offers that are available to a billing unit.", "parameters": [ { "name": "billing_unit_id", "in": "query", "required": true, "description": "The billing unit ID", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Return results up to this limit. Valid values are between 0 and 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "start", "in": "query", "required": false, "description": "The pagination offset. This represents the index of the first returned result.", "schema": { "type": "string" } } ], "x-ibm-permissions": { "actions": [ { "name": "billing.billing-unit.read" } ] }, "responses": { "200": { "description": "Status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingOptionsList" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } }, "404": { "description": "Billing unit not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } }, "412": { "description": "Failure to resolve enterprise account ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } }, "500": { "description": "Unexpected errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } } }, "x-sdk-operations": { "request-examples": { "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "listBillingOptionsOptions := enterpriseBillingUnitsService.NewListBillingOptionsOptions(\n", " billingUnitID,\n", ")\n", "\n", "billingOption, response, err := enterpriseBillingUnitsService.ListBillingOptions(listBillingOptionsOptions)\n", "if err != nil {\n", " panic(err)\n", "}\n", "b, _ := json.MarshalIndent(billingOption, \"\", \" \")\n", "fmt.Println(string(b))" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "ListBillingOptionsOptions listBillingOptionsOptions = new ListBillingOptionsOptions.Builder()\n", " .billingUnitId(billingUnitId)\n", " .build();\n", "\n", "Response response = service.listBillingOptions(listBillingOptionsOptions).execute();\n", "BillingOptionsList billingOptionsList = response.getResult();\n", "\n", "System.out.println(billingOptionsList);" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const params = {\n", " billingUnitId: billingUnitId,\n", "};\n", "\n", "enterpriseBillingUnitsService.listBillingOptions(params)\n", " .then(res => {\n", " console.log(JSON.stringify(res.result, null, 2));\n", " })\n", " .catch(err => {\n", " console.warn(err)\n", " });" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "billing_options_list = enterprise_billing_units_service.list_billing_options(\n", " billing_unit_id=billing_unit_id).get_result()\n", "\n", "print(json.dumps(billing_options_list, indent=2))" ] } ] } ] } } } }, "/v1/credit-pools": { "get": { "summary": "Get credit pools", "description": "Get credit pools for a billing unit. Credit pools can be either platform or support credit pools. The platform credit pool contains credit from platform subscriptions and promotional offers. The support credit pool contains credit from support subscriptions.", "tags": [ "Credit Pools" ], "operationId": "get_credit_pools", "parameters": [ { "name": "billing_unit_id", "in": "query", "required": true, "description": "The ID of the billing unit.", "schema": { "type": "string" } }, { "name": "date", "in": "query", "description": "The date in the format of YYYY-MM.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Filters the credit pool by type, either `PLATFORM` or `SUPPORT`.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Return results up to this limit. Valid values are between 0 and 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "start", "in": "query", "required": false, "description": "The pagination offset. This represents the index of the first returned result.", "schema": { "type": "string" } } ], "x-ibm-permissions": { "actions": [ { "name": "billing.billing-unit.read" } ] }, "responses": { "200": { "description": "The request to retrieve credit pools was successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditPoolsList" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } }, "500": { "description": "Unexpected internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } } }, "x-sdk-operations": { "request-examples": { "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "getCreditPoolsOptions := enterpriseBillingUnitsService.NewGetCreditPoolsOptions(\n", " billingUnitID,\n", ")\n", "\n", "creditPoolsList, response, err := enterpriseBillingUnitsService.GetCreditPools(getCreditPoolsOptions)\n", "if err != nil {\n", " panic(err)\n", "}\n", "b, _ := json.MarshalIndent(creditPoolsList, \"\", \" \")\n", "fmt.Println(string(b))" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "GetCreditPoolsOptions getCreditPoolsOptions = new GetCreditPoolsOptions.Builder()\n", " .billingUnitId(billingUnitId)\n", " .build();\n", "\n", "Response response = service.getCreditPools(getCreditPoolsOptions).execute();\n", "CreditPoolsList creditPoolsList = response.getResult();\n", "\n", "System.out.println(creditPoolsList);" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const params = {\n", " billingUnitId: billingUnitId,\n", "};\n", "\n", "enterpriseBillingUnitsService.getCreditPools(params)\n", " .then(res => {\n", " console.log(JSON.stringify(res.result, null, 2));\n", " })\n", " .catch(err => {\n", " console.warn(err)\n", " });" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "credit_pools_list = enterprise_billing_units_service.get_credit_pools(\n", " billing_unit_id=billing_unit_id, type='PLATFORM').get_result()\n", "\n", "print(json.dumps(credit_pools_list, indent=2))" ] } ] } ] } } } } }, "components": { "securitySchemes": { "IAM": { "type": "apiKey", "name": "Authorization", "description": "Your IBM Cloud IAM access token.", "in": "header" } }, "schemas": { "BillingOption": { "type": "object", "description": "Information about a billing option.", "properties": { "id": { "type": "string", "description": "The ID of the billing option." }, "billing_unit_id": { "type": "string", "description": "The ID of the billing unit that's associated with the billing option." }, "start_date": { "type": "string", "format": "date-time", "description": "The start date of billing option.", "example": "2019-05-01T00:00:00.000Z" }, "end_date": { "type": "string", "format": "date-time", "description": "The end date of billing option.", "example": "2020-05-01T00:00:00.000Z" }, "state": { "type": "string", "description": "The state of the billing option. The valid values include `ACTIVE, `SUSPENDED`, and `CANCELED`.", "enum": [ "ACTIVE", "SUSPENDED", "CANCELED" ], "example": "ACTIVE" }, "type": { "type": "string", "description": "The type of billing option. The valid values are `SUBSCRIPTION` and `OFFER`.", "enum": [ "SUBSCRIPTION", "OFFER" ], "example": "SUBSCRIPTION" }, "category": { "type": "string", "description": "The category of the billing option. The valid values are `PLATFORM`, `SERVICE`, and `SUPPORT`.", "enum": [ "PLATFORM", "SERVICE", "SUPPORT" ], "example": "PLATFORM" }, "payment_instrument": { "type": "object", "description": "The payment method for support.", "additionalProperties": true }, "duration_in_months": { "type": "integer", "description": "The duration of the billing options in months.", "example": 11 }, "line_item_id": { "type": "integer", "description": "The line item ID for support.", "example": 10 }, "billing_system": { "type": "object", "description": "The support billing system.", "additionalProperties": true }, "renewal_mode_code": { "type": "string", "description": "The renewal code for support. This code denotes whether the subscription automatically renews, is assessed monthly, and so on." }, "updated_at": { "type": "string", "format": "date-time", "description": "The date when the billing option was updated.", "example": "2019-06-01T00:00:00.000Z" } }, "example": { "id": "CFL_JJKLVZ2I0JE-_MGU", "billing_unit_id": "e19fa97c9bb34963a31a2008044d8b59", "start_date": "2019-05-02T07:00:00.000Z", "end_date": "2019-11-30T08:00:00.000Z", "state": "ACTIVE", "type": "SUBSCRIPTION", "category": "PLATFORM", "payment_instrument": { "type": "PURCHASE_ORDER", "authorization_code": "", "fraud_profile": {} }, "renewal_mode_code": "T", "duration_in_months": 6, "monthly_amount": 1000, "catalog_id": "", "line_item_id": 10, "billing_system": { "type": "DSW", "properties": { "charge_agreement_number": 77158598, "partner_customer_number": 7006381 } }, "updated_at": "2019-05-02T07:00:00.000Z" } }, "BillingOptionsList": { "type": "object", "description": "A search result containing zero or more billing options.", "properties": { "rows_count": { "type": "integer", "description": "A count of the billing units that were found by the query." }, "next_url": { "type": "string", "description": "Bookmark URL to query for next batch of billing units. This returns `null` if no additional pages are required." }, "resources": { "type": "array", "description": "A list of billing units found.", "items": { "$ref": "#/components/schemas/BillingOption" } } }, "example": { "rows_count": 3, "resources": [ { "id": "CFL_JJKLVZ2I0JE-_MGU", "billing_unit_id": "e19fa97c9bb34963a31a2008044d8b59", "start_date": "2019-05-02T07:00:00.000Z", "end_date": "2019-11-30T08:00:00.000Z", "state": "ACTIVE", "type": "SUBSCRIPTION", "category": "PLATFORM", "payment_instrument": { "type": "PURCHASE_ORDER", "authorization_code": "", "fraud_profile": {} }, "renewal_mode_code": "T", "duration_in_months": 6, "monthly_amount": 1000, "catalog_id": "", "line_item_id": 10, "billing_system": { "type": "DSW", "properties": { "charge_agreement_number": 77158598, "partner_customer_number": 7006381 } }, "updated_at": "2019-05-02T07:00:00.000Z" } ] } }, "BillingUnit": { "type": "object", "description": "Information about a billing unit.", "properties": { "id": { "type": "string", "description": "The ID of the billing unit, which is a globally unique identifier (GUID)." }, "crn": { "type": "string", "description": "The Cloud Resource Name (CRN) of the billing unit, scoped to the enterprise account ID.", "example": "crn:v1:bluemix:public:billing::a/<>::billing-unit:<>" }, "name": { "type": "string", "description": "The name of the billing unit." }, "enterprise_id": { "type": "string", "description": "The ID of the enterprise to which the billing unit is associated." }, "currency_code": { "type": "string", "description": "The currency code for the billing unit.", "example": "USD" }, "country_code": { "type": "string", "description": "The country code for the billing unit.", "example": "USA" }, "master": { "type": "boolean", "description": "A flag that indicates whether this billing unit is the primary billing mechanism for the enterprise.", "example": true }, "created_at": { "type": "string", "format": "date-time", "description": "The creation date of the billing unit.", "example": "2019-05-01T00:00:00.000Z" } }, "example": { "id": "$BILLING_UNIT_ID", "crn": "crn:v1:bluemix:public:billing::a/$ENTERPRISE_ACCOUNT_ID::billing-unit:$BILLING_UNIT_ID", "name": "Sample Billing Unit", "enterprise_id": "$ENTERPRISE_ID", "country_code": "USA", "currency_code": "USD", "master": true, "created_at": "2019-07-01T00:00:00.000Z" } }, "BillingUnitsList": { "type": "object", "description": "A search result contining zero or more billing units.", "properties": { "rows_count": { "type": "integer", "description": "A count of the billing units that were found by the query." }, "next_url": { "type": "string", "description": "Bookmark URL to query for next batch of billing units. This returns `null` if no additional pages are required." }, "resources": { "type": "array", "description": "A list of billing units found.", "items": { "$ref": "#/components/schemas/BillingUnit" } } }, "example": { "rows_count": 1, "resources": [ { "id": "$BILLING_UNIT_ID", "crn": "crn:v1:bluemix:public:billing::a/$ENTERPRISE_ACCOUNT_ID::billing-unit:$BILLING_UNIT_ID", "name": "Sample Billing Unit", "enterprise_id": "$ENTERPRISE_ID", "country_code": "USA", "currency_code": "USD", "master": true, "created_at": "2019-07-01T00:00:00.000Z" } ] } }, "CreditPool": { "type": "object", "description": "The credit pool for a billing unit.", "properties": { "type": { "type": "string", "description": "The type of credit, either `PLATFORM` or `SUPPORT`.", "enum": [ "PLATFORM", "SUPPORT" ] }, "currency_code": { "type": "string", "description": "The currency code of the associated billing unit.", "example": "USD" }, "billing_unit_id": { "type": "string", "description": "The ID of the billing unit that's associated with the credit pool. This value is a globally unique identifier (GUID)." }, "term_credits": { "type": "array", "description": "A list of active subscription terms available within a credit pool.", "items": { "$ref": "#/components/schemas/TermCredits" } }, "overage": { "type": "object", "description": "Overage that was generated on the credit pool.", "properties": { "cost": { "type": "number", "description": "The number of credits used as overage.", "example": 500 }, "resources": { "type": "array", "description": "A list of resources that generated overage.", "items": { "type": "object", "additionalProperties": true } } } } }, "example": { "type": "PLATFORM", "billing_unit_id": "$BILLING_UNIT_ID", "currency_code": "USD", "term_credits": [ { "billing_option_id": "$BILLING_OPTION_ID", "category": "PLATFORM", "start_date": "2019-07-01T01:00:00.000Z", "end_date": "2020-06-30T23:59:59.999Z", "total_credits": 7000, "starting_balance": 6000, "used_credits": 1000, "current_balance": 5000, "resources": [] }, { "billing_option_id": "$BILLING_OPTION_ID_2", "category": "PLATFORM", "start_date": "2019-06-02T07:00:00.000Z", "end_date": "2019-12-31T08:00:00.000Z", "total_credits": 14000, "starting_balance": 14000, "used_credits": 0, "current_balance": 14000, "resources": [] } ], "overage": { "cost": 0, "resources": [] } } }, "TermCredits": { "type": "object", "description": "The subscription term that is active in the current month.", "properties": { "billing_option_id": { "type": "string", "description": "The ID of the billing option from which the subscription term is derived.", "example": "JWX986YRGFSHACQUEFOI" }, "category": { "type": "string", "description": "The category of the credit pool. The valid values are `PLATFORM`, `OFFER`, or `SERVICE` for platform credit and `SUPPORT` for support credit.", "enum": [ "PLATFORM", "OFFER", "SERVICE", "SUPPORT" ], "example": "PLATFORM" }, "start_date": { "type": "string", "format": "date-time", "description": "The start date of the term in ISO format.", "example": "2019-05-01T00:00:00.000Z" }, "end_date": { "type": "string", "format": "date-time", "description": "The end date of the term in ISO format.", "example": "2020-04-30T23:59:29.999Z" }, "total_credits": { "type": "number", "description": "The total credit available in this term.", "example": 10000 }, "starting_balance": { "type": "number", "description": "The balance of available credit at the start of the current month.", "example": 9000 }, "used_credits": { "type": "number", "description": "The amount of credit used during the current month.", "example": 9500 }, "current_balance": { "type": "number", "description": "The balance of remaining credit in the subscription term.", "example": 0 }, "resources": { "type": "array", "description": "A list of resources that used credit during the month.", "items": { "type": "object", "additionalProperties": true } } }, "example": { "billing_option_id": "$BILLING_OPTION_ID", "category": "PLATFORM", "start_date": "2019-07-01T01:00:00.000Z", "end_date": "2020-06-30T23:59:59.999Z", "total_credits": 7000, "starting_balance": 6000, "used_credits": 1000, "current_balance": 5000, "resources": [] } }, "CreditPoolsList": { "type": "object", "description": "A search result containing zero or more credit pools.", "properties": { "rows_count": { "type": "integer", "description": "The number of credit pools that were found by the query.", "example": 2 }, "next_url": { "type": "string", "description": "A bookmark URL to the query for the next batch of billing units. Use a value of `null` if no additional pages are required." }, "resources": { "type": "array", "description": "A list of credit pools found by the query.", "items": { "$ref": "#/components/schemas/CreditPool" } } }, "example": { "rows_count": 2, "resources": [ { "type": "PLATFORM", "billing_unit_id": "$BILLING_UNIT_ID", "currency_code": "USD", "term_credits": [ { "billing_option_id": "$BILLING_OPTION_ID", "category": "PLATFORM", "start_date": "2019-07-01T01:00:00.000Z", "end_date": "2020-06-30T23:59:59.999Z", "total_credits": 7000, "starting_balance": 6000, "used_credits": 1000, "current_balance": 5000, "resources": [] }, { "billing_option_id": "$BILLING_OPTION_ID_2", "category": "PLATFORM", "start_date": "2019-06-02T07:00:00.000Z", "end_date": "2019-12-31T08:00:00.000Z", "total_credits": 14000, "starting_balance": 14000, "used_credits": 0, "current_balance": 14000, "resources": [] } ], "overage": { "cost": 0, "resources": [] } }, { "type": "SUPPORT", "billing_unit_id": "$BILLING_UNIT_ID", "currency_code": "USD", "term_credits": [ { "category": "SUPPORT", "start_date": "2019-07-01T00:00:00.000Z", "end_date": "2019-08-31T23:59:59.999Z", "total_credits": 125, "starting_balance": 125, "used_credits": 0, "current_balance": 125, "resources": [] } ], "overage": { "cost": 0, "resources": [] } } ] } }, "ErrorModel": { "type": "object", "description": "The format of the error response.", "properties": { "error_description": { "type": "string", "description": "A message that describes the error." } }, "example": { "error_description": "An error occurred in your request." } } } } }