All Products
Search

This Product

    Expenses and Costs:DescribeInstanceBill

    Document Center

    Expenses and Costs:DescribeInstanceBill

    Last Updated:Oct 28, 2025

    Queries the consumption summary of all product instances or billable items for an account within a billing cycle.

    Operation description

    • Data for the current month is for reference only and may be adjusted during the month due to delayed billing, refunds, adjustments, or write-offs for overdue payments. The final bill is available after 12:00 on the third day of the next month.

    • The bill data for the current month does not include pay-as-you-go resources that are not yet settled.

    • You can query data from the past 18 months.

    • Bill data is updated with a 24-hour delay compared to actual usage. Information related to instance IDs is updated with a 48-hour delay. This includes instance configurations, instance types, instance nicknames, resource groups, public IP addresses, private IP addresses, and zones.

    • Bill data does not provide costs for individual attached resources of services such as CDN, OSS, and Internet Shared Bandwidth. For example, costs are not provided for individual domain names, buckets, or EIPs. To view the costs of attached resources, go to the Split Bill page.

    • For Alibaba Cloud Communications products, you can query bill details only starting in June 2020. For HiChina products, including Domain Names and trademarks, you can query details for bills from November 2020 onward.

    • Each account can make up to 10 queries per second. If a timeout error occurs, try again.

    Try it now

    Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

    Test

    RAM authorization

    The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

    • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

    • API: The API that you can call to perform the action.

    • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

    • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

      • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

      • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

    • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

    • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

    Action

    Access level

    Resource type

    Condition key

    Dependent action

    bssapi:DescribeInstanceBill

    get

    *All Resource

    *

    • bssapi:ProductCode

    • bssapi:ProductCode

    • bssapi:ProductType

    • bssapi:ProductType

    None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example

    BillingCycle

    string

    Yes

    The billing cycle in YYYY-MM format. Only billing cycles within the past 18 months are supported.

    2020-03

    ProductCode

    string

    No

    The product code.

    rds

    ProductType

    string

    No

    The product type.

    rds

    SubscriptionType

    string

    No

    The subscription type. Valid values:

    • Subscription: subscription

    • PayAsYouGo: pay-as-you-go

    PayAsYouGo

    IsBillingItem

    boolean

    No

    Specifies whether to pull data by billing item dimension.

    • false (default): The data is consistent with the Instance Bill page under Expenses and Costs > Bills > Bill Details.

    • true: The data is consistent with the Billing Item Bill page under Expenses and Costs > Bills > Bill Details.

    false

    NextToken

    string

    No

    The token that specifies the starting point for reading data. Leave this parameter empty to read the first page of results. To read the next page, set this parameter to the NextToken value that was returned in the previous response. Any other value will cause an error.

    CAESEgoQCg4KCm

    MaxResults

    integer

    No

    The maximum number of data records to return. Default value: 20. Maximum value: 300.

    20

    IsHideZeroCharge

    boolean

    No

    Specifies whether to exclude bills where both PretaxGrossAmount and PretaxAmount are 0.

    • false

    • true

    false

    BillingDate

    string

    No

    The bill date. This parameter is required only when Granularity is set to DAILY. The format is YYYY-MM-DD.

    Note

    The month of BillingDate must match the month of BillingCycle. For example, if BillingCycle is 2020-03, BillingDate must be in the format 2020-03-DD. If the months do not match, the query returns results based on the BillingCycle setting.

    2020-03-02

    Granularity

    string

    No

    The granularity of the bills to query. Valid values:

    • MONTHLY: Monthly. This corresponds to the bills on the Bills by Billing Cycle tab of the Bill Details page.

    • DAILY: Daily. This corresponds to the bills on the Bills by Day tab of the Bill Details page.

    Note

    Specify BillingDate if you select DAILY.

    MONTHLY

    BillOwnerId

    integer

    No

    The ID of the resource ownership account. This is the account that actually uses the resources.

    122

    InstanceID

    string

    No

    The instance ID.

    abc

    PipCode

    string

    No

    The product code. This is the same as the product code on the bill in the User Center.

    rds

    Response elements

    Parameter

    Type

    Description

    Example

    object

    Code

    string

    The status code.

    Success

    Message

    string

    The error message.

    Successful!

    RequestId

    string

    The request ID.

    79EE7556-0CFD-44EB-9CD6-B3B526E3A85F

    Success

    boolean

    Indicates whether the request was successful.

    true

    Data

    object

    The returned data.

    NextToken

    string

    The token that marks the position for the next query. An empty value indicates that all data has been read. To continue the query, set the NextToken request parameter to this value in your next call.

    CAESEgoQCg4KCm

    BillingCycle

    string

    The billing date. Format: YYYY-MM.

    2020-03

    MaxResults

    integer

    The maximum number of records returned per page.

    20

    AccountID

    string

    The account ID.

    122

    TotalCount

    integer

    The total number of records.

    20

    AccountName

    string

    The user account.

    test@test.aliyunid.com

    Items

    array<object>

    The bill details.

    object

    BillingDate

    string

    The billing date is in YYYY-MM-DD format. This parameter has a value only when Granularity is set to DAILY.

    2020-03-20

    InstanceConfig

    string

    The detailed configuration of the instance.

    CPU：12

    InternetIP

    string

    The public IP address.

    34.xx.x.x

    Item

    string

    The bill type:

    • SubscriptionOrder: A prepaid order.

    • PayAsYouGoBill: A postpaid bill.

    • Refund: A refund.

    • Adjustment: An adjustment.

    PayAsYouGoBill

    Tag

    string

    The tag of the resource.

    key:testKey value:testValue; key:testKey1 value:testValues1

    InstanceID

    string

    The instance ID.

    i-dadada

    Currency

    string

    The currency. Valid values:

    • CNY

    • USD

    • JPY

    CNY

    BillAccountName

    string

    The name of the account associated with the bill.

    test@test.aliyunid.com

    DeductedByCashCoupons

    number

    The amount deducted by cash coupons.

    0.1

    SubscriptionType

    string

    The subscription type. Valid values:

    • Subscription: Subscription.

    • PayAsYouGo: Pay-as-you-go.

    PayAsYouGo

    BizType

    string

    The service type.

    trusteeship

    InstanceSpec

    string

    The instance type.

    ecs.sn1ne.3xlarge

    DeductedByCoupons

    number

    The amount deducted by coupons.

    0.1

    BillingItem

    string

    The billing item. This property has a value only when IsBillingItem is true.

    带宽

    BillingItemCode

    string

    The billing item code.

    disk

    Region

    string

    The region.

    杭州

    OutstandingAmount

    number

    The outstanding amount.

    0.1

    CostUnit

    string

    The cost center.

    未分配

    ListPriceUnit

    string

    The unit of the list price. This parameter is valid only when isBillingItem is true.

    元

    ResourceGroup

    string

    The resource group.

    默认资源组

    PipCode

    string

    The product code. It is the same as the product code on the bill in the User Center.

    rds

    ServicePeriodUnit

    string

    The unit of the service period.

    秒

    PretaxAmount

    number

    The pretax amount.

    0.1

    CommodityCode

    string

    The product code. This is the same as the product detail code in the User Center.

    rds

    ProductName

    string

    The name of the product.

    云数据库RDS

    AdjustAmount

    number

    The offset for a credit refund.

    0

    NickName

    string

    The nickname of the instance.

    test

    ProductDetail

    string

    The details of the product.

    云数据库RDS

    Usage

    string

    The usage.

    Note

    This parameter is valid only when isBillingItem is set to true. The usage data is the total usage from all bills in an epoch, not the actual purchased amount. For example, if you use 1 GB of storage and a bill is generated every hour, the hourly usage is 1 GB. The daily usage on the bill is 1 GB × 24 = 24 GB.

    100

    IntranetIP

    string

    The internal IP address.

    192.xx.xx.xx

    OwnerID

    string

    The Account ID of the resource owner in a multi-account payment scenario.

    123

    DeductedByPrepaidCard

    number

    The amount deducted by a prepaid card.

    0.1

    UsageUnit

    string

    The usage unit. This parameter is valid only when isBillingItem is true.

    GB

    BillAccountID

    string

    The ID of the account to which the bill belongs.

    122

    PaymentAmount

    number

    The cash payment. This includes payments covered by refunds issued as credit.

    0.1

    InvoiceDiscount

    number

    The discount amount.

    0.1

    DeductedByResourcePackage

    string

    The amount deducted by the resource plan. This parameter is valid only when isBillingItem is true.

    0.1

    ProductType

    string

    The product type.

    rds

    ServicePeriod

    string

    The service period.

    3600

    Zone

    string

    The zone.

    杭州1

    ListPrice

    string

    The list price. This is valid only when isBillingItem is true.

    100

    PretaxGrossAmount

    number

    The original amount.

    0.1

    CashAmount

    number

    The amount paid in cash. This excludes offsets from credit line refunds.

    0

    ProductCode

    string

    The product code.

    rds

    BillingType

    string

    The billing method.

    其它

    ItemName

    string

    The name of the project.

    iZ28bycvyb4Z

    AfterDiscountAmount

    number

    The amount after a discount is applied. This amount includes the payable amount after coupon deductions. The formula is: Discounted amount = List price - Discount amount.

    Examples

    Success response

    JSON format

    {
  "Code": "Success",
  "Message": "Successful!",
  "RequestId": "79EE7556-0CFD-44EB-9CD6-B3B526E3A85F",
  "Success": true,
  "Data": {
    "NextToken": "CAESEgoQCg4KCm",
    "BillingCycle": "2020-03",
    "MaxResults": 20,
    "AccountID": "122",
    "TotalCount": 20,
    "AccountName": "test@test.aliyunid.com",
    "Items": [
      {
        "BillingDate": "2020-03-20",
        "InstanceConfig": "CPU：12",
        "InternetIP": "34.xx.x.x\t",
        "Item": "PayAsYouGoBill",
        "Tag": "key:testKey value:testValue; key:testKey1 value:testValues1",
        "InstanceID": "i-dadada",
        "Currency": "CNY",
        "BillAccountName": "test@test.aliyunid.com",
        "DeductedByCashCoupons": 0.1,
        "SubscriptionType": "PayAsYouGo",
        "BizType": "trusteeship",
        "InstanceSpec": "ecs.sn1ne.3xlarge\t",
        "DeductedByCoupons": 0.1,
        "BillingItem": "带宽",
        "BillingItemCode": "disk",
        "Region": "杭州",
        "OutstandingAmount": 0.1,
        "CostUnit": "未分配\t",
        "ListPriceUnit": "元",
        "ResourceGroup": "默认资源组\t",
        "PipCode": "rds",
        "ServicePeriodUnit": "秒",
        "PretaxAmount": 0.1,
        "CommodityCode": "rds",
        "ProductName": "云数据库RDS\t",
        "AdjustAmount": 0,
        "NickName": "test",
        "ProductDetail": "云数据库RDS\t",
        "Usage": "100",
        "IntranetIP": "192.xx.xx.xx",
        "OwnerID": "123",
        "DeductedByPrepaidCard": 0.1,
        "UsageUnit": "GB",
        "BillAccountID": "122",
        "PaymentAmount": 0.1,
        "InvoiceDiscount": 0.1,
        "DeductedByResourcePackage": "0.1",
        "ProductType": "rds",
        "ServicePeriod": "3600",
        "Zone": "杭州1",
        "ListPrice": "100",
        "PretaxGrossAmount": 0.1,
        "CashAmount": 0,
        "ProductCode": "rds",
        "BillingType": "其它",
        "ItemName": "iZ28bycvyb4Z",
        "AfterDiscountAmount": 0
      }
    ]
  }
}

    Error codes

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.