Add and use billing tags

The billing tag provides a way to track your platform usage across components which track usage and costs.

Using billing tags, you can create a string that is used for combining expenses on your invoices. For example, you can group multiple pipelines together for a project or activity where you want to highlight those specific costs.

Add user-defined billing tags

User-defined billing tags have the following rules:

  • between four-16 characters
  • case-sensitive
  • allowed characters are alpha/numeric ASCII characters [A-Za-z0-9] and the following special characters: [ - ] [ _ ]
  • the billing tag is not allowed to begin or end with the special characters: [ - ] [ _ ]
  • up to six billing tags can be concatenated with + to a long string, for example, tag1+tag2+tag3+tag4+tag5+tag6

An invalid billing tag results in the following error:

{
  "title": "billingTag is invalid",                    
  "status": 400,                                                      
  "code": "<to be defined by the service>",                            
  "cause": "The billingTag passed does not meet validation rules",
  "action": "Please provide a valid billingTag according to service specification",
  "correlationId": "4199533b-6290-41db-8d79-edf4f4019a74"          
}

Valid and invalid characters

The account management paradigm known as "Technical Accounting" removes invalid characters from faulty billing tags. For example, "My#In%validTag_ThatIsVeryLong" → "MyInvalidTag_Tha".

Account management paradigm

The following table shows some valid billing tags.

Sample Text
https://samplehost/sampleresource?billingTag=ABC&other_tag=123
https://samplehost/sampleresource?billingTag=DEF+GHI&other_tag=123
https://samplehost/sampleresource?billingTag=ABC2&other_tag=123B
https://samplehost/sampleresource?billingTag=DEF2+GHI2&other_tag=olp-test-123C
Regex for a single billing tag
([A-Za-z0-9][A-Za-z0-9-_]{2,14}[A-Za-z0-9])
Regex for multiple, concatenated billing tags
([A-Za-z0-9][A-Za-z0-9-]{2,14}[A-Za-z0-9])(+([A-Za-z0-9][A-Za-z0-9-]{2,14}[A-Za-z0-9])){0,5}

Billing tag for Projects

The part of the account management paradigm known as "Projects" is identified by the following:

Purpose Example
name non-unique, purpose for UI "Happy Project"
id constructed from name for uniqueness in a organization "project/happy-project"
hrn globally unique identifier "hrn:here:authorization::olp-here:project/happy-project"
scope scope in token = hrn "hrn:here:authorization::olp-here:project/happy-project"

The cost allocation for projects is handled internally and is independent from user-defined billing tags. The scope from the token is extracted and is used as billingTag, for example,hrn:here:authorization::olp-here:project/happy-project, as shown in the previous table, where the project, happy-project, is the billing tag.

The project related billing tag appears in your invoicing for the specific project cost split.

Get usage by billing tag

You can use the billing tag to get your usage amount, as shown here. This example uses testtag as the billing tag.

Request

    GET https://usage.bam.api.here.com/v2/usage/realms/org123456789?startDate=2021-07-01T10:39:51&endDate=2021-08-30T10:39:51&billingTag=testtag

Parameters

realmId required string [ 5 .. 30 ] characters
Example: org123456789
Your org ID.
startTime
required
string
Example: startTime=yyyy-MM-dd'T'HH:mm:ss
Start date for history search.
endTime
required
string
Example: endTime=yyyy-MM-dd'T'HH:mm:ss
End date for history search.
featureId string less than or equal to 256 characters
Example: featureId=hrn:here:service::org123456789:search-geocoding-1
Feature HRN.
appId string less than or equal to 128 characters
Example: appId=j1dasda012edasfgne
Client application ID. This is the application ID which was created in the platform.
channelId string
Enum: "hot" "cold"
Example: channelId=cold
When this parameter is provided, the results are filtered by the ID identifying the channel for the usage reporting.
projectHrn string less than or equal to 256 characters
Example: projectHrn=hrn:here:authorization::myrealm:project/my-project-0000
The HRN which identifies the project.
billingTag string less than or equal to 500 characters
Example: billingTag=testtag
The billing tag.
category string less than or equal to 128 characters
Example: category=Pipelines
The category.
limit integer [ 1 .. 100 ]
Example: category=Pipelines
Default: 100
Number of records to return. The default and maximum is 100 records.
offset integer >= 0
Example: offset=1
Default: 0
Offset page number. The default value is 0.
detailLevel string
Enum: "summarized" "hour" "day" "month"
Example: detailLevel=hour
Default: 0
This query parameter controls granularity of records at the levels of summarized, hour, day, or month. By default, `detailLevel` is set to summarized, which means the granularity is at the search criteria level. The `usageDateTime` field value is not present if `detailLevel` is set to summarized.
groupBy string less than or equal to 256 characters
Example: `groupBy=appId`, `billingTag`, `project`, `resource`, `usageTypeCode`
Comma seperated list of `groupBy`. Supported values are `project`, `billingTag`, `usageTypeCode`, and `appId`. The default `groupBy` is `featureId` and `subscriptionId`. The `groupBy` query parameter controls the additional dimensions included in a response. By default, usage records are grouped by `featureId` (charge Item) and `subscriptionId`, which means that the only dimensions included are `featureId` and `subscriptionId`. When additional `groupBy` are added through the query parameter, it is in addition to `featureId` and `subscriptionId`.
usageFields Array of strings unique
Items Enum: "`realmId`" "`featureId`" "`billingSubscriptionId`" "`billingChargeNumber`" "`category`" "`name`" "`valueDriver`" "`usageValue`" "`billableValue`"
Example: `usageFields`=`realmId`,`featureId`,`category`
A set of unique/distinct usage field names which are allowed to filter response objects properties.

Header parameters

X-Request-ID string
User-provided token that can be used to trace a request or a group of requests sent to the service.
X-Correlation-ID
required
string
Auto-generated ID, which uniquely identifies the request, available in the response. When contacting the support with an inquiry regarding a specific request, provide the value of this header; This assists with troubleshooting the issue.

Response: HTTP 200 OK

{
    "total": 2,
    "limit": 100,
    "items": [
        {
            "realmId": "org123456789",
            "featureId": "hrn:here:service::org123456789:feature1",
            "category": "Location Services",
            "name": "Autocomplete",
            "valueDriver": "Transactions",
            "usageValue": 144940.0000,
            "billableValue": 144940.0000
        },
        {
            "realmId": "org123456789",
            "featureId": "hrn:here:service::org123456789:feature2",
            "category": "Location Services",
            "name": "Geocode & Reverse Geocode",
            "valueDriver": "Transactions",
            "usageValue": 91932.0000,
            "billableValue": 91932.0000
        }
    ],
    "nextOffset": 0,
    "lastOffset": 0
}

Get usage csv by billing tag

You can retrieve the usage in csv format using the billing tag, as shown here. This example uses testtag as the billing tag.

Request

    GET https://usage.bam.api.here.com/v2/usage/realms/org123456789/csv?startDate=2021-07-01T10:39:51&endDate=2021-08-30T10:39:51&billingTag=testtag

Response: HTTP 200 OK

"Date and time (usageDateTime)","Org ID (realmId)","Category (category)","App ID (appId)","Item (featureId)","Subscription ID (billingSubscriptionId)","Resource ID (resourceHrn)","Item description (name)","Unit (valueDriver)","Project ID (projectHrn)","Billing tag (billingTag)","Usage Amount (billableValue)","Charge Number (billingChargeNumber)","Usage Amount (usageValue)"
"","org123456789","Location Services","","hrn:here:service::org123456789:feature1","","","Autocomplete","Transactions","","","144940.0000","","144940.0000"
"","org123456789","Location Services","","hrn:here:service::org123456789:feature2","","","Geocode & Reverse Geocode","Transactions","","","91932.0000","","91932.0000"

results matching ""

    No results matching ""