Updated on 2024-10-29 GMT+08:00

Viewing Resource Usage Details

Function

This API can be used to query usage details of each resource for a customer on the self-built platform.

Postpaid customers who have enabled the monthly settlement can log in to Billing Center to query their resource usage details by referring to Resource Bill.

  • After a customer associates with an enterprise master in the unified accounting model, bill queries will return both bills before and after the association.
  • You can query data from the past three years.

Constraints

This API can be invoked only by the customer AK/SK or token.

You can debug the API in API Explorer which supports automatic authentication. API Explorer can automatically generate and debug example SDK code.

URI

POST /v2/bills/customer-bills/res-records/query

Table 1 Header parameters

Parameter

Mandatory

Maximum Length

Description

X-Language

No

10

Language.

  • zh_CN: Chinese
  • en_US: English

The default value is en_US.

Request Message

Request Parameters

Parameter

Mandatory

Type

Maximum Length

Description

cycle

Yes

String

8

Billing cycle of the queried resource usage details, which is in YYYY-MM format (GMT+08:00).

Example: 2019-01

cloud_service_type

No

String

64

Cloud service type code. For example, the cloud service type code of OBS is hws.service.type.obs. To obtain a specific service type, call the API in Querying Cloud Service Types.

If this parameter is not included in the request parameters, is set to "", or is set to null, it cannot be used as a filter criterion.

resource_type

No

String

64

Resource type code. For example, the VM resource type code of ECS is hws.resource.type.vm. To obtain a specific resource type, call the API in Querying Resource Types.

If this parameter is not included in the request parameters, is set to "", or is set to null, it cannot be used as a filter criterion.

region

No

String

64

Cloud service region code, for example, ap-southeast-1. Obtain the value from the Region column in Regions and Endpoints.

If this parameter is not included in the request parameters, is set to "", or is set to null, it cannot be used as a filter criterion.

res_instance_id

No

String

64

Resource instance ID.

If this parameter is not included in the request parameters, is set to "", or is set to null, it cannot be used as a filter criterion.

charge_mode

No

Integer

-

Billing mode. The options are as follows:

  • 1: Yearly/monthly
  • 3: Pay-per-use
  • 10: Reserved instances
  • 11: savings plan

If this parameter is not included in the request parameters or is set to null, usage details of resources of all billing modes are returned.

bill_type

No

Integer

-

Bill type:

  • 1: expenditure-purchase
  • 2: expenditure-renewal
  • 3: expenditure-change
  • 4: refund-unsubscription
  • 5: expenditure-use
  • 8: expenditure-auto-renewal
  • 9: adjustment-compensation
  • 14: expenditure-month-end deduction for support plan
  • 15: expenditure-tax
  • 16: adjustment-deduction
  • 17: expenditure-difference amount (min. guaranteed-actual)
    NOTE:

    Expenditure-difference amount (min. guaranteed-actual) determines the fees that a customer needs to pay if the customer does not reach the minimum expenditure limit stipulated in the signed contract. This rule is applicable to direct sales customers and referral customers who use postpaid method.

  • 20: refund-change
  • 23: savings plans used
  • 24: refund-changing to Pay-Per-Use
  • 100: refund-unsubscription tax
  • 101: adjustment-tax compensation
  • 102: adjustment-tax deduction

If this parameter is not included in the request parameters or is set to null, usage details of resources of all bill types are returned.

enterprise_project_id

No

String

64

Enterprise project ID.

  • 0: ID of a default project
  • – 1: The service does not support enterprise project management.

If this parameter is not included in the request parameters, is set to "", or is set to null, it cannot be used as a filter criterion.

include_zero_record

No

Boolean

-

Whether to return records for which the amount due is 0.

  • true: Yes
  • false: No

If this parameter is not included in the request parameters, is set to "", or is set to null, it cannot be used as a filter criterion.

method

No

String

64

Query method.

  • oneself: Query the resource usage details of an enterprise itself.
  • sub_customer: Query the resource usage details of enterprise's sub-customers.
  • all: Query the resource usage details of an enterprise and its sub-customers.

If this parameter is not included in the request parameters, is set to "", or is set to null, the default value is all. If this parameter is set to all and an enterprise has no customers, the enterprise queries its own resource usage details.

sub_customer_id

No

String

64

Enterprise member account ID.

NOTE:
  • This parameter is invalid if method is not set to sub_customer.
  • If method is set to sub_customer, this parameter must be specified.

offset

No

Integer

0 to a maximum integer

Offset, which starts from 0. The default value is 0.

NOTE:

This parameter is used for pagination. Retain its default value 0 if pagination is not required. offset indicates the offset relative to the first data record among all that meets the conditions configured. If you set offset to 1, the second and subsequent data records are returned.

For example, if there are 10 records that meet query conditions, when you set limit to 10 and offset to 1, the second to the tenth records are returned.

If there are 20 records that meet query conditions, when you set offset to 0 and limit to 10 for the first page and set offset to 10 and limit to 10 for the second page, then each page will respectively have 10 records.

limit

No

Integer

1–1000

Page limit. The default value is 10.

statistic_type

No

Integer

1–3

Statistics type. The default value is 1.

  • 1: By billing cycle
  • 2: By day
  • 3: By details

If this parameter is not included in the request parameters or is set to null, the default value 1 is used. It cannot be set to "".

query_type

No

String

0–9

Type of information to be queried. The default value is BILLCYCLE.

  • BILLCYCLE: By billing cycle.
  • DAILY: By day

The information type, DAILY, is returned only when the statistic_type is set to 2 or 3.

If this parameter is not included in the request or is set to null or "", the information type, BILLCYCLE, is returned by default.

bill_cycle_begin

No

String

0–10

The start time of a billing cycle. Format: YYYY-MM-DD.

This parameter is mandatory when query_type is set to DAILY.

If this parameter is not included in the request or is set to null or "", it cannot be used as a filter criterion.

NOTE:
  • This parameter is invalid if query_type is not set to DAILY.
  • If query_type is set to DAILY, this parameter cannot be left empty and the month must be consistent with the billing cycle.

bill_cycle_end

No

String

0–10

The end time of a billing cycle. Format: YYYY-MM-DD.

This parameter is mandatory when query_type is set to DAILY.

If this parameter is not included in the request or is set to null or "", it cannot be used as a filter criterion.

NOTE:
  • This parameter is invalid if query_type is not set to DAILY.
  • If query_type is set to DAILY, this parameter cannot be left empty and the value must be consistent with the billing cycle.

payer_account_id

No

String

1–64

The account ID of the payer.

If this parameter is not included or is set to null, it will not be used as a filter criterion. It cannot be set to "".

NOTE:
  • Independent accounting members of an enterprise and other common customers can only query their own expenditures.
  • For an enterprise master, if this parameter is not included, expenditures of the master, their unified accounting members, and their independent account members are returned; if this parameter is set to the ID of the master, expenditures of the master and their unified accounting members are returned; and if this parameter is set to the ID of an independent accounting member, expenditures of this member are returned.
  • For a unified accounting member of an enterprise, if this parameter is set to the ID of the member, expenditures of the member generated before they were associated with their enterprise master are returned; if this parameter is set to their enterprise master, expenditures of the member generated after they were associated with their enterprise master are returned; and if this parameter is not included, all expenditures are returned.

Example Request

POST https://bss-intl.myhuaweicloud.com/v2/bills/customer-bills/res-records/query HTTP/1.1
Content-Type: application/json
X-Auth-Token: MIIPAgYJKoZIhvcNAQcCo...ggg1BBIINPXsidG9rZ
X-Language:en_US
{
      "cycle": "2018-12",
      "cloud_service_type": "hws.service.type.ec2",
      "resource_type": "hws.resource.type.vm",
      "region": "ap-southeast-1",
      "res_instance_id": "76*****7f",
      "charge_mode": 1,
      "bill_type": 1,
      "enterprise_project_id": "6***f3-3**4-4**2-9a3e-a****c24",
      "include_zero_record": "true",
       "method": "sub_customer",
       "sub_customer_id": "05b5fef62300d2ad0f98c00befba72c0",
       "offset": 1,
       "limit": 10
}

Response Message

Response Parameters

Parameter

Type

Maximum Length

Description

error_code

String

16

Status code. For details, see Status Code. This parameter is returned only when a failure occurs.

error_msg

String

1024

Error description. This parameter is returned only when a failure occurs.

monthly_records

List<MonthlyBillRes>

-

Resource records.

For details, see Table 2.

total_count

Integer

-

Number of result sets. This parameter is returned only when the query is successful.

currency

String

3

Currency.

USD

Table 2 MonthlyBillRes

Parameter

Type

Maximum Length

Description

cycle

String

8

Billing cycle of resource data, which is in YYYY-MM format (GMT+08:00).

Example: 2020-01

bill_date

String

10

Consumption date, which is in the YYYY-MM-DD format (GMT+08:00)

NOTE:

This parameter has a value only when statistic_type is set to 2. Otherwise, null is returned.

bill_type

Integer

-

Bill type.

  • 1: expenditure-purchase
  • 2: expenditure-renewal
  • 3: expenditure-change
  • 4: refund-unsubscription
  • 5: expenditure-use
  • 8: expenditure-auto-renewal
  • 9: adjustment-compensation
  • 14: expenditure-month-end deduction for support plan
  • 15: expenditure-tax
  • 16: adjustment-deduction
  • 17: expenditure-difference amount (min. guaranteed-actual)
    NOTE:

    Expenditure-difference amount (min. guaranteed-actual) determines the fees that a customer needs to pay if the customer does not reach the minimum expenditure limit stipulated in the signed contract. This rule is applicable to direct sales customers and referral customers who use postpaid method.

  • 20: refund-change
  • 23: savings plans used
  • 24: refund-changing to Pay-Per-Use
  • 100: refund-unsubscription tax
  • 101: adjustment-tax compensation
  • 102: adjustment-tax deduction

customer_id

String

64

ID of the account that has consumption records.

  • If a common account or enterprise member account is used to query consumption records, only the ID of the customer itself is displayed.
  • If an enterprise master account is used to query consumption records, the consumption records of its own and its member accounts can be queried. The ID of a master or member account will be displayed.

region

String

64

Cloud service region code, for example, ap-southeast-1. Obtain the value from the Region column in Regions and Endpoints.

region_name

String

64

Region name, for example, CN-Hong Kong. Obtain the value from the Region column in Regions and Endpoints..

cloud_service_type

String

256

Cloud service type code. For example, the cloud service type code of OBS is hws.service.type.obs.

resource_Type_code

String

64

Resource type code. For example, the resource type code of ECS is hws.resource.type.vm.

cloud_service_type_name

String

200

Cloud service type. For example, the cloud service type of ECS is Elastic Cloud Server.

resource_type_name

String

200

Resource type. For example, the resource type of ECS is Cloud Host.

res_instance_id

String

256

Resource instance ID.

resource_name

String

-

Resource name. When creating a resource, a customer can enter the resource name. Some resource names can also be changed during resource management.

root_resource_id

String

-

Root resource ID

parent_resource_id

String

-

Parent resource ID

resource_tag

String

8,192

Resource tag. Customers can set tags when managing resources.

sku_code

String

64

SKU code, which uniquely identifies the resource specification in a bill.

enterprise_project_id

String

-

Enterprise project ID.

  • 0: ID of a default project
  • null: The service does not support enterprise project management.

enterprise_project_name

String

-

Enterprise project name.

charge_mode

Integer

-

Billing mode. The options are as follows:

  • 1: Yearly/monthly
  • 3: Pay-per-use
  • 10: Reserved instances
  • 11: savings plan

consume_amount

BigDecimal

-

Consumption amount of a cloud service, including the amount of cash coupons and that of flexi-purchase coupons, accurate to eight decimal places.

NOTE:

The value of consume_amount is equal to the sum of the values of cash_amount, credit_amount, coupon_amount, flexipurchase_coupon_amount, stored_card_amount, bonus_amount, debt_amount, and adjustment_amount.

cash_amount

BigDecimal

-

Amount paid in cash.

credit_amount

BigDecimal

-

Amount paid using the credit.

coupon_amount

BigDecimal

-

Amount paid using the cash coupon.

flexipurchase_coupon_amount

BigDecimal

-

Amount paid using the flexi-purchase coupon.

stored_card_amount

BigDecimal

-

Amount paid using the values-stored card.

bonus_amount

BigDecimal

-

Bonus payment amount (used for the bonus that is not cleared on the live network).

debt_amount

BigDecimal

-

Monthly-paid user: monthly settlement (For details about monthly settlement, click here.)

Non-monthly-paid subscriber: outstanding amount

adjustment_amount

BigDecimal

-

Adjustment amount.

official_amount

BigDecimal

-

Standard price.

discount_amount

BigDecimal

-

Discount amount (based on the standard price).

measure_id

Integer

-

Unit.

  • 1: USD

period_type

Integer

-

Period type. The value can be:

  • 19: Year
  • 20: Month
  • 24: Day
  • 25: Hour
  • 5: One-off

trade_id

String

-

Order ID or transaction ID.

  • If the value of bill_type is 1, 2, 3, 4, or 8, this field indicates the order ID.
  • In other scenarios, it indicates the transaction ID (this parameter represents bills when fees are deducted at the end of a month. Otherwise, this parameter represents receivables.)

id

String

256

Unique ID.

This parameter is reserved.

product_spec_desc

String

-

Product specification description.

sub_service_type_code

String

64

Service type code of a child service that is attached to an ECS.

sub_service_type_name

String

200

Service type of a child service that is attached to an ECS.

sub_resource_type_code

String

64

Resource type code of a child resource that is attached to an ECS.

sub_resource_type_name

String

200

Resource type name of a child resource that is attached to an ECS.

sub_resource_id

String

64

Resource ID of a child resource that is attached to an ECS. If the resource is a reserved instance, this parameter indicates a reserved instance ID.

sub_resource_name

String

256

Resource name of a child resource that is attached to an ECS. If the resource is a reserved instance, this parameter indicates a reserved instance name.

pre_order_id

String

64

Original order ID

az_code_infos

List<AzCodeInfo>

-

AZ information list For details, see Table 3.

payer_account_id

String

64

The account ID of the payer.

NOTE:
  • If the current account is an individual account, an account of an independent accounting member, or an enterprise master account, this parameter needs to be set to the ID of the current account.
  • For a unified accounting member of an enterprise, this parameter can be set to the ID of the unified accounting member or the ID of their enterprise master.

effective_time

String

32

Start time of using the resource corresponding to the fee.

This field is valid when statistic_type is set to 3. This field is reserved when statistic_type is set to 1 or 2.

expire_time

String

32

End time of using the resource corresponding to the fee.

This field is valid when statistic_type is set to 3. This field is reserved when statistic_type is set to 1 or 2.

Table 3 AzCodeInfo

Parameter

Type

Maximum Length

Description

az_code

String

64

AZ code

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: length
Date: response time  
{
	"monthly_records": [{
		"cycle": "2022-05",
		"bill_date": null,
		"bill_type": 4,
		"customer_id": "05f2******00d50d0f2bc002c46e3020",
		"region": "ap-southeast-1",
                     "region_name": "CN-Hong Kong",
		"cloud_service_type": "hws.service.type.ebs",
		"resource_Type_code": "hws.resource.type.volume",
               "cloud_service_type_name": "Elastic Volume Service",
               "resource_type_name": "Elastic Volume Service",
		"res_instance_id": "220523_dbc6ee4a02964e04adaa0e01b7a1e8e4",
		"resource_name": "hws.resource.type.volumename",
		"resource_tag": null,
		"sku_code": "SATA",
		"enterprise_project_id": null,
               "enterprise_project_name": "Non-project"
		"charge_mode": 1,
		"consume_amount": 0.0,
		"cash_amount": 0.0,
		"credit_amount": 0.0,
		"coupon_amount": 0.0,
		"flexipurchase_coupon_amount": 0.0,
		"stored_card_amount": 0.0,
		"bonus_amount": 0.0,
		"debt_amount": 0.0,
		"adjustment_amount": null,
		"official_amount": 0.0,
		"discount_amount": 0,
		"id": "037e8a2b******01-5f9eb5153cba_1",
		"measure_id": 1,
                "sub_service_type_code": null,
                "sub_service_type_name": null,
                "sub_resource_type_code": null,
                "sub_resource_type_name": null,
                "sub_resource_id": null,
                "sub_resource_name": null,
		"period_type": 20,
		"root_resource_id": null,
		"parent_resource_id": null,
		"trade_id": "CSYD******214V3CC02",
		"product_spec_desc": "Common I/O|200GB",
                "pre_order_id": "CS23******54B1AEW4J",
		"az_code_infos": [{
			"az_code": "cn-north-1c"
		}],
                "payer_account_id": "ZS78******56A1BEF4J",
                "effective_time": "2024-07-06T16:00:00Z",
                "expire_time": "2024-08-06T16:00:00Z"
	}],
	"total_count": 7,
	"currency": "USD"
}

Status Code

  • 4xx: This class of HTTP status code is intended for situations in which the error seems to have been caused by the client, for example, the request contains bad syntax or incorrect parameters. You must ensure the request is correct.
  • 5xx: This class of HTTP status code is intended for cases in which the Huawei Cloud server is aware that it has encountered an error or is otherwise incapable of performing the request. In this case, contact Huawei Cloud customer service.

HTTP Value

Error Code

Description

400

CBC.0100

Parameter error.

403

CBC.0151

Access denied.

500

CBC.0999

Unknown error occurred.