IBM Cloud API Docs

Introduction

In 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 manage billing and usage with enterprises.

SDKs 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 on GitHub.

Installing the Java SDK

Maven

<dependency>
	<groupId>com.ibm.cloud</groupId>
	<artifactId>enterprise-billing-units</artifactId>
	<version>{version}</version>
</dependency>

Gradle

compile 'com.ibm.cloud:enterprise-billing-units:{version}'

Replace {version} in these examples with the release version.

View on GitHub

Installing the Node SDK

npm install ibm-platform-services

View on GitHub

Installing the Python SDK

pip

pip install --upgrade "ibm-platform-services"

View on GitHub

Installing the Go SDK

Go modules (recommended): Add the following import in your code, and then run go build or go mod tidy

import (
	"github.com/IBM/platform-services-go-sdk/enterprisebillingunitsv1"
)

Go get

go get -u github.com/IBM/platform-services-go-sdk/enterprisebillingunitsv1

View on GitHub

Endpoint URLs

The 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.

https://billing.cloud.ibm.com

If 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.

  • Private endpoint URL for VPC infrastructure: https://private.billing.cloud.ibm.com
  • Private endpoint URL (Dallas) for classic infrastructure: https://private.us-south.billing.cloud.ibm.com

Example API request

curl --request POST --header "content-type: application/json" --header "accept: application/json" --header "authorization: Bearer <IAM token>" --data "{\"query\":\"string\"}" --url "https://api.billing.cloud.ibm.com/v1/resources/billing-options

Replace <IAM token> in this example with the value for your particular API call.

Authentication

Authorization 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.

Obtaining an IAM token for an authenticated user or service ID is described in the IAM Identity Services API documentation.

To use the API, add a valid IAM token to the HTTP Authorization request header, for example, -H 'Authorization: Bearer <TOKEN>'.

When 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:

  • Programmatically by constructing an IAM authenticator instance and supplying your IAM API key
  • 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

In 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.

For more information, see the Authentication section of the IBM Cloud SDK Common documentation.

To 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.

To retrieve your access token:

curl -X POST   "https://iam.cloud.ibm.com/identity/token"   --header 'Content-Type: application/x-www-form-urlencoded'   --header 'Accept: application/json'   --data-urlencode 'grant_type=urn:ibm:params:oauth:grant-type:apikey'   --data-urlencode 'apikey=<API_KEY>'

Replace <API_KEY> with your IAM API key.

Setting client options through external configuration

Example environment variables, where <SERVICE_URL> is the endpoint URL and <API_KEY> is your IAM API key

export ENTERPRISE_BILLING_UNITS_URL=<SERVICE_URL>
export ENTERPRISE_BILLING_UNITS_AUTHTYPE=iam
export ENTERPRISE_BILLING_UNITS_APIKEY=<API_KEY>

Example of constructing the service client

import {
    "github.com/IBM/platform-services-go-sdk/enterprisebillingunitsv1"
}
...
serviceClientOptions := &enterprisebillingunitsv1.EnterpriseBillingUnitsV1Options{}
serviceClient, err := enterprisebillingunitsv1.NewEnterpriseBillingUnitsV1UsingExternalConfig(serviceClientOptions)

Setting client options through external configuration

Example environment variables, where <SERVICE_URL> is the endpoint URL and <API_KEY> is your IAM API key

export ENTERPRISE_BILLING_UNITS_URL=<SERVICE_URL>
export ENTERPRISE_BILLING_UNITS_AUTHTYPE=iam
export ENTERPRISE_BILLING_UNITS_APIKEY=<API_KEY>

Example of constructing the service client

import com.ibm.cloud.platform_services.enterprise_billing_units.v1.EnterpriseBillingUnits;
...
EnterpriseBillingUnits serviceClient = EnterpriseBillingUnits.newInstance();

Setting client options through external configuration

Example environment variables, where <SERVICE_URL> is the endpoint URL and <API_KEY> is your IAM API key

export ENTERPRISE_BILLING_UNITS_URL=<SERVICE_URL>
export ENTERPRISE_BILLING_UNITS_AUTHTYPE=iam
export ENTERPRISE_BILLING_UNITS_APIKEY=<API_KEY>

Example of constructing the service client

const EnterpriseBillingUnitsV1 = require('ibm-platform-services/enterprise-billing-units/v1');
...
const serviceClient = EnterpriseBillingUnitsV1.newInstance();

Setting client options through external configuration

Example environment variables, where <SERVICE_URL> is the endpoint URL and <API_KEY> is your IAM API key

export ENTERPRISE_BILLING_UNITS_URL=<SERVICE_URL>
export ENTERPRISE_BILLING_UNITS_AUTHTYPE=iam
export ENTERPRISE_BILLING_UNITS_APIKEY=<API_KEY>

Example of constructing the service client

from ibm_platform_services import EnterpriseBillingUnitsV1
...
service_client = EnterpriseBillingUnitsV1.new_instance()

Error handling

The 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.

HTTP Code Description Recovery
200 Success The request was successful.
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.
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.
403 Authorization Failed The supplied authentication is not authorized to access '{namespace}'.
404 Not Found The required resource was not found.
412 Precondition Failed The server failed to resolve account ID by request header fields.
424 Dependency Failure The dependencies for the entity are not set up correctly. The dependencies must be correct before a report can be generated.
5xx Internal Server Error offering name is currently unavailable. Your request could not be processed. Wait a few minutes and try again.

Pagination

Some API requests might return a large number of 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:

  • /v1/billing-units?:query
  • /v1/billing-options?:query
  • /v1/credit-pools?:query

The 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. The default page size is 100 items, which is also the maximum size of responses on a page. To use a different page size, use the limit query parameter. The rows_count field indicates the number of resources that exist on the page.

See the following related APIs for managing IBM Cloud enterprises:

Methods

Get billing unit by ID

Return the billing unit information if it exists.

Return the billing unit information if it exists.

Return the billing unit information if it exists.

Return the billing unit information if it exists.

Return the billing unit information if it exists.

GET /v1/billing-units/{billing_unit_id}
(enterpriseBillingUnits *EnterpriseBillingUnitsV1) GetBillingUnit(getBillingUnitOptions *GetBillingUnitOptions) (result *BillingUnit, response *core.DetailedResponse, err error)
(enterpriseBillingUnits *EnterpriseBillingUnitsV1) GetBillingUnitWithContext(ctx context.Context, getBillingUnitOptions *GetBillingUnitOptions) (result *BillingUnit, response *core.DetailedResponse, err error)
ServiceCall<BillingUnit> getBillingUnit(GetBillingUnitOptions getBillingUnitOptions)
getBillingUnit(params)
get_billing_unit(self,
        billing_unit_id: str,
        **kwargs
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • billing.billing-unit.read

Request

Instantiate the GetBillingUnitOptions struct and set the fields to provide parameter values for the GetBillingUnit method.

Use the GetBillingUnitOptions.Builder to create a GetBillingUnitOptions object that contains the parameter values for the getBillingUnit method.

Path Parameters

  • The ID of the requested billing unit.

WithContext method only

The GetBillingUnit options.

The getBillingUnit options.

parameters

  • The ID of the requested billing unit.

parameters

  • The ID of the requested billing unit.

  • getBillingUnitOptions := enterpriseBillingUnitsService.NewGetBillingUnitOptions(
      billingUnitID,
    )
    
    billingUnit, response, err := enterpriseBillingUnitsService.GetBillingUnit(getBillingUnitOptions)
    if err != nil {
      panic(err)
    }
    b, _ := json.MarshalIndent(billingUnit, "", "  ")
    fmt.Println(string(b))
  • GetBillingUnitOptions getBillingUnitOptions = new GetBillingUnitOptions.Builder()
      .billingUnitId(billingUnitId)
      .build();
    
    Response<BillingUnit> response = service.getBillingUnit(getBillingUnitOptions).execute();
    BillingUnit billingUnit = response.getResult();
    
    System.out.println(billingUnit);
  • const params = {
      billingUnitId: billingUnitId,
    };
    
    enterpriseBillingUnitsService.getBillingUnit(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • billing_unit = enterprise_billing_units_service.get_billing_unit(
      billing_unit_id=billing_unit_id).get_result()
    
    print(json.dumps(billing_unit, indent=2))

Response

Information about a billing unit.

Information about a billing unit.

Examples:
View

Information about a billing unit.

Examples:
View

Information about a billing unit.

Examples:
View

Information about a billing unit.

Examples:
View

Status Code

  • Status 200

  • Unauthenticated

  • Unauthorized

  • Billing unit not found

  • Failure to resolve enterprise account ID

  • Unexpected errors

Example responses
  • {
      "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"
    }
  • {
      "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"
    }
  • {
      "error_description": "An error occurred in your request."
    }
  • {
      "error_description": "An error occurred in your request."
    }
  • {
      "error_description": "An error occurred in your request."
    }
  • {
      "error_description": "An error occurred in your request."
    }
  • {
      "error_description": "An error occurred in your request."
    }
  • {
      "error_description": "An error occurred in your request."
    }
  • {
      "error_description": "An error occurred in your request."
    }
  • {
      "error_description": "An error occurred in your request."
    }
  • {
      "error_description": "An error occurred in your request."
    }
  • {
      "error_description": "An error occurred in your request."
    }

List billing units

Return matching billing unit information if any exists. Omits internal properties and enterprise account ID from the billing unit.

Return matching billing unit information if any exists. Omits internal properties and enterprise account ID from the billing unit.

Return matching billing unit information if any exists. Omits internal properties and enterprise account ID from the billing unit.

Return matching billing unit information if any exists. Omits internal properties and enterprise account ID from the billing unit.

Return matching billing unit information if any exists. Omits internal properties and enterprise account ID from the billing unit.

GET /v1/billing-units
(enterpriseBillingUnits *EnterpriseBillingUnitsV1) ListBillingUnits(listBillingUnitsOptions *ListBillingUnitsOptions) (result *BillingUnitsList, response *core.DetailedResponse, err error)
(enterpriseBillingUnits *EnterpriseBillingUnitsV1) ListBillingUnitsWithContext(ctx context.Context, listBillingUnitsOptions *ListBillingUnitsOptions) (result *BillingUnitsList, response *core.DetailedResponse, err error)
ServiceCall<BillingUnitsList> listBillingUnits(ListBillingUnitsOptions listBillingUnitsOptions)
listBillingUnits(params)
list_billing_units(self,
        *,
        account_id: str = None,
        enterprise_id: str = None,
        account_group_id: str = None,
        **kwargs
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • billing.billing-unit.read

Request

Instantiate the ListBillingUnitsOptions struct and set the fields to provide parameter values for the ListBillingUnits method.

Use the ListBillingUnitsOptions.Builder to create a ListBillingUnitsOptions object that contains the parameter values for the listBillingUnits method.

Query Parameters

  • The enterprise account ID.

  • The enterprise ID.

  • The account group ID.

  • Return results up to this limit. Valid values are between 0 and 100.

    Possible values: 1 ≤ value ≤ 100

    Default: 100

  • The pagination offset. This represents the index of the first returned result.

WithContext method only

The ListBillingUnits options.

The listBillingUnits options.

parameters

  • The enterprise account ID.

  • The enterprise ID.

  • The account group ID.

parameters

  • The enterprise account ID.

  • The enterprise ID.

  • The account group ID.

  • listBillingUnitsOptions := enterpriseBillingUnitsService.NewListBillingUnitsOptions()
    listBillingUnitsOptions.SetEnterpriseID(enterpriseID)
    
    billingUnitsList, response, err := enterpriseBillingUnitsService.ListBillingUnits(listBillingUnitsOptions)
    if err != nil {
      panic(err)
    }
    b, _ := json.MarshalIndent(billingUnitsList, "", "  ")
    fmt.Println(string(b))
  • ListBillingUnitsOptions listBillingUnitsOptions = new ListBillingUnitsOptions.Builder()
      .enterpriseId(enterpriseId)
      .build();
    
    Response<BillingUnitsList> response = service.listBillingUnits(listBillingUnitsOptions).execute();
    BillingUnitsList billingUnitsList = response.getResult();
    
    System.out.println(billingUnitsList);
  • const params = {
      enterpriseId: enterpriseId,
    };
    enterpriseBillingUnitsService.listBillingUnits(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • billing_units_list = enterprise_billing_units_service.list_billing_units(
      enterprise_id=enterprise_id).get_result()
    
    print(json.dumps(billing_units_list, indent=2))

Response

A search result contining zero or more billing units.

A search result contining zero or more billing units.

Examples:
View

A search result contining zero or more billing units.

Examples:
View

A search result contining zero or more billing units.

Examples:
View

A search result contining zero or more billing units.

Examples:
View

Status Code

  • Status 200

  • Unauthenticated

  • Unauthorized

  • Billing unit not found

  • Failure to resolve enterprise account ID

  • Unexpected errors

Example responses
  • {
      "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"
        }
      ]
    }
  • {
      "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"
        }
      ]
    }
  • {
      "error_description": "An error occurred in your request."
    }
  • {
      "error_description": "An error occurred in your request."
    }
  • {
      "error_description": "An error occurred in your request."
    }
  • {
      "error_description": "An error occurred in your request."
    }
  • {
      "error_description": "An error occurred in your request."
    }
  • {
      "error_description": "An error occurred in your request."
    }
  • {
      "error_description": "An error occurred in your request."
    }
  • {
      "error_description": "An error occurred in your request."
    }
  • {
      "error_description": "An error occurred in your request."
    }
  • {
      "error_description": "An error occurred in your request."
    }

List billing options

Return matching billing options if any exist. Show subscriptions and promotional offers that are available to a billing unit.

Return matching billing options if any exist. Show subscriptions and promotional offers that are available to a billing unit.

Return matching billing options if any exist. Show subscriptions and promotional offers that are available to a billing unit.

Return matching billing options if any exist. Show subscriptions and promotional offers that are available to a billing unit.

Return matching billing options if any exist. Show subscriptions and promotional offers that are available to a billing unit.

GET /v1/billing-options
(enterpriseBillingUnits *EnterpriseBillingUnitsV1) ListBillingOptions(listBillingOptionsOptions *ListBillingOptionsOptions) (result *BillingOptionsList, response *core.DetailedResponse, err error)
(enterpriseBillingUnits *EnterpriseBillingUnitsV1) ListBillingOptionsWithContext(ctx context.Context, listBillingOptionsOptions *ListBillingOptionsOptions) (result *BillingOptionsList, response *core.DetailedResponse, err error)
ServiceCall<BillingOptionsList> listBillingOptions(ListBillingOptionsOptions listBillingOptionsOptions)
listBillingOptions(params)
list_billing_options(self,
        billing_unit_id: str,
        **kwargs
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • billing.billing-unit.read

Request

Instantiate the ListBillingOptionsOptions struct and set the fields to provide parameter values for the ListBillingOptions method.

Use the ListBillingOptionsOptions.Builder to create a ListBillingOptionsOptions object that contains the parameter values for the listBillingOptions method.

Query Parameters

  • The billing unit ID

  • Return results up to this limit. Valid values are between 0 and 100.

    Possible values: 1 ≤ value ≤ 100

    Default: 100

  • The pagination offset. This represents the index of the first returned result.

WithContext method only

The ListBillingOptions options.

The listBillingOptions options.

parameters

  • The billing unit ID.

parameters

  • The billing unit ID.

  • listBillingOptionsOptions := enterpriseBillingUnitsService.NewListBillingOptionsOptions(
      billingUnitID,
    )
    
    billingOption, response, err := enterpriseBillingUnitsService.ListBillingOptions(listBillingOptionsOptions)
    if err != nil {
      panic(err)
    }
    b, _ := json.MarshalIndent(billingOption, "", "  ")
    fmt.Println(string(b))
  • ListBillingOptionsOptions listBillingOptionsOptions = new ListBillingOptionsOptions.Builder()
      .billingUnitId(billingUnitId)
      .build();
    
    Response<BillingOptionsList> response = service.listBillingOptions(listBillingOptionsOptions).execute();
    BillingOptionsList billingOptionsList = response.getResult();
    
    System.out.println(billingOptionsList);
  • const params = {
      billingUnitId: billingUnitId,
    };
    
    enterpriseBillingUnitsService.listBillingOptions(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • billing_options_list = enterprise_billing_units_service.list_billing_options(
      billing_unit_id=billing_unit_id).get_result()
    
    print(json.dumps(billing_options_list, indent=2))

Response

A search result containing zero or more billing options.

A search result containing zero or more billing options.

Examples:
View

A search result containing zero or more billing options.

Examples:
View

A search result containing zero or more billing options.

Examples:
View

A search result containing zero or more billing options.

Examples:
View

Status Code

  • Status 200

  • Unauthenticated

  • Unauthorized

  • Billing unit not found

  • Failure to resolve enterprise account ID

  • Unexpected errors

Example responses
  • {
      "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"
        }
      ]
    }
  • {
      "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"
        }
      ]
    }
  • {
      "error_description": "An error occurred in your request."
    }
  • {
      "error_description": "An error occurred in your request."
    }
  • {
      "error_description": "An error occurred in your request."
    }
  • {
      "error_description": "An error occurred in your request."
    }
  • {
      "error_description": "An error occurred in your request."
    }
  • {
      "error_description": "An error occurred in your request."
    }
  • {
      "error_description": "An error occurred in your request."
    }
  • {
      "error_description": "An error occurred in your request."
    }
  • {
      "error_description": "An error occurred in your request."
    }
  • {
      "error_description": "An error occurred in your request."
    }

Get credit pools

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.

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.

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.

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.

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.

GET /v1/credit-pools
(enterpriseBillingUnits *EnterpriseBillingUnitsV1) GetCreditPools(getCreditPoolsOptions *GetCreditPoolsOptions) (result *CreditPoolsList, response *core.DetailedResponse, err error)
(enterpriseBillingUnits *EnterpriseBillingUnitsV1) GetCreditPoolsWithContext(ctx context.Context, getCreditPoolsOptions *GetCreditPoolsOptions) (result *CreditPoolsList, response *core.DetailedResponse, err error)
ServiceCall<CreditPoolsList> getCreditPools(GetCreditPoolsOptions getCreditPoolsOptions)
getCreditPools(params)
get_credit_pools(self,
        billing_unit_id: str,
        *,
        date: str = None,
        type: str = None,
        **kwargs
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • billing.billing-unit.read

Request

Instantiate the GetCreditPoolsOptions struct and set the fields to provide parameter values for the GetCreditPools method.

Use the GetCreditPoolsOptions.Builder to create a GetCreditPoolsOptions object that contains the parameter values for the getCreditPools method.

Query Parameters

  • The ID of the billing unit.

  • The date in the format of YYYY-MM.

  • Filters the credit pool by type, either PLATFORM or SUPPORT.

  • Return results up to this limit. Valid values are between 0 and 100.

    Possible values: 1 ≤ value ≤ 100

    Default: 100

  • The pagination offset. This represents the index of the first returned result.

WithContext method only

The GetCreditPools options.

The getCreditPools options.

parameters

  • The ID of the billing unit.

  • The date in the format of YYYY-MM.

  • Filters the credit pool by type, either PLATFORM or SUPPORT.

parameters

  • The ID of the billing unit.

  • The date in the format of YYYY-MM.

  • Filters the credit pool by type, either PLATFORM or SUPPORT.

  • getCreditPoolsOptions := enterpriseBillingUnitsService.NewGetCreditPoolsOptions(
      billingUnitID,
    )
    
    creditPoolsList, response, err := enterpriseBillingUnitsService.GetCreditPools(getCreditPoolsOptions)
    if err != nil {
      panic(err)
    }
    b, _ := json.MarshalIndent(creditPoolsList, "", "  ")
    fmt.Println(string(b))
  • GetCreditPoolsOptions getCreditPoolsOptions = new GetCreditPoolsOptions.Builder()
      .billingUnitId(billingUnitId)
      .build();
    
    Response<CreditPoolsList> response = service.getCreditPools(getCreditPoolsOptions).execute();
    CreditPoolsList creditPoolsList = response.getResult();
    
    System.out.println(creditPoolsList);
  • const params = {
      billingUnitId: billingUnitId,
    };
    
    enterpriseBillingUnitsService.getCreditPools(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • credit_pools_list = enterprise_billing_units_service.get_credit_pools(
      billing_unit_id=billing_unit_id, type='PLATFORM').get_result()
    
    print(json.dumps(credit_pools_list, indent=2))

Response

A search result containing zero or more credit pools.

A search result containing zero or more credit pools.

Examples:
View

A search result containing zero or more credit pools.

Examples:
View

A search result containing zero or more credit pools.

Examples:
View

A search result containing zero or more credit pools.

Examples:
View

Status Code

  • The request to retrieve credit pools was successful.

  • Unauthenticated

  • Unauthorized

  • Unexpected internal error

Example responses
  • {
      "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": []
          }
        }
      ]
    }
  • {
      "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": []
          }
        }
      ]
    }
  • {
      "error_description": "An error occurred in your request."
    }
  • {
      "error_description": "An error occurred in your request."
    }
  • {
      "error_description": "An error occurred in your request."
    }
  • {
      "error_description": "An error occurred in your request."
    }
  • {
      "error_description": "An error occurred in your request."
    }
  • {
      "error_description": "An error occurred in your request."
    }