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.

Endpoints

Get billing unit by billing unit ID: https://billing.cloud.ibm.com/v1/billing-units/:billing_unit_id

Get billing unit by query: https://billing.cloud.ibm.com/v1/billing-units?:query

Get billing options: https://billing.cloud.ibm.com/v1/billing-options?:query

Get credit pools: https://billing.cloud.ibm.com/v1/credit-pools?:query

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response indicates success. A 400 type response indicates a failure, and a 500 type response indicates 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 incorrect. Be sure to validate your request.
401 Authentication Failed The token that is provided in the Authorization header is invalid or expired.
403 Authorization Failed The subject does not have access to the reports.
404 Not Found The entity does not exist.
412 Precondition Failed Failed to resolve account ID by request header fields.
424 Dependency Failure The dependencies for the entity are not set up correctly. The dependencies need to be fixed before a report can be generated.
5xx Internal Server Error The API is currently unavailable. Your request could not be processed. Wait a few minutes and try again.

Authentication

Access to the Enterprise Billing Unit API is enforced through IBM Cloud Identity and Access Management (IAM) access tokens. To retrieve billing units, the user must have either the Administrator or Editor role on the Billing service in the enterprise account. For more information about these roles, see Assigning access to account management services.

-H 'Authorization: Bearer <IAM_TOKEN>'

You can retrieve an access token by first creating an API key, and then exchanging your API key for an IBM Cloud IAM token. For more information, see Getting an IBM Cloud IAM token by using an API key.

See the following related APIs for managing IBM Cloud enterprises:

Methods

Get billing unit by ID

Return the billing unit information if it exists.

GET /v1/billing-units/{billing_unit_id}
Request

Path Parameters

  • The ID of the requested billing unit.

Response

Aggregated usage and charges for all the plans in the account.

Status Code

  • Status 200

  • Unauthenticated

  • Unauthorized

  • Billing unit not found

  • Unexpected errors

Example responses

Get billing unit by query

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

GET /v1/billing-units
Request

Query Parameters

  • The enterprise account ID.

  • The enterprise ID.

  • The account group ID.

Response

Aggregated usage and charges for all the plans in the account.

Status Code

  • Status 200

  • Unauthenticated

  • Unauthorized

  • Billing unit not found

  • Unexpected errors

Example responses

Get billing options by query

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

GET /v1/billing-options
Request

Query Parameters

  • The billing unit ID

Response

A container for all the plans in the resource.

Status Code

  • Status 200

  • Unauthenticated

  • Unauthorized

  • Billing unit not found

  • Unexpected errors

Example responses

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 /v1/credit-pools
Request

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.

Response

Aggregated usage and charges for all the plans in the account.

Status Code

  • The request to retrieve credit pools was successful.

  • Unauthenticated

  • Unauthorized

Example responses