You are here: Usage Information > retrieveUsageBilling

Retrieve Usage Bill

Description

Retrieve the billing data for a specific product included in an entitlement. Different type of bills that you can view are:

This data is partially processed data that can be used as the basis of generating bills, but is not the actual bill. This will need further processing before it can be used for billing purposes.

Default Protocol Method Type URI

HTTPS

GET

retrieveUsageBilling.xml

Query Parameters

Parameter Description Valid Values Default Value Optional

entId

Identifier of the entitlement.

Note: The entId is the handle returned by the createEntitlement.xml web service. You can use the searchEntitlements.xml web service to retrieve entId for an entitlement.

Integer

 

No

billType

Bill type. The options are:

  • 1: Brief bill
  • 2: Detailed bill
  • 3: Itemized bill

Integer

 

No

productName Name of the product

String

  No
productVersion Version of the product String   No

startdate

Start date from when the usage bill is to be obtained.

The startDate should be earlier than or same as the enddate.

String (yyyy-mm-dd)

 

No

enddate

End date till when the usage bill is to be obtained.

String (yyyy-mm-dd)

 

No

 Sample Code

import java.io.IOException;
import java.net.URLDecoder;
//..............................
//..............................
//..............................
import org.apache.http.params.HttpParams;
public class EMSSample {
        private static DefaultHttpClient httpclient = new DefaultHttpClient();
        private static Principal principal = null;
        private static StringBuffer query;
        //..............................
        //..............................
        //..............................
        public static String retrieveUsageBilling.xml()throws Exception {
                if(!verifyLogin()){
                        return "login failed";
                }
                HttpContext context = new BasicHttpContext();
                context.setAttribute(ClientContext.USER_TOKEN, principal);
                HttpGet get = new HttpGet("https://localhost:8080/ems/3.6/retrieveUsageBilling.xml");
                query = new StringBuffer();
                setParameter("billType", "");
                setParameter("startdate", "");
                setParameter("entId", "");
                setParameter("enddate", "");
                setParameter("productVersion", "");
                setParameter("productName", "");
                get.setURI(new URI(URLDecoder.decode(get.getURI() + query.toString(),"UTF-8")));
                HttpResponse response = httpclient.execute(get, context);
                HttpEntity entity = response.getEntity();
                byte[] b = null;
                if (entity != null) {
                        long l = entity.getContentLength();
                        b = new byte[(int) l];
                        entity.getContent().read(b);
                        entity.consumeContent();
                }
                return new String(b);
        }
        static void setParameter(String key, String value) {
                if (query.toString().equals("")) {
                        query.append("?" + key + "=" + value + "&");
                } else {
                        query.append(key + "=" + value + "&");
                }
        }
}

Sample Response

ClosedBrief Billing

 <!--This is an automated/formatted XML output for the queried ISV aggregation information.-->
<BriefBillingInformation>
  <ProductInformation>
    <ProductName>Pro_1</ProductName>
    <ProductVersion>209_1</ProductVersion>
    <ContractID>5519dded-51e9-46cf-b6b3-68774958cac6</ContractID>
    <TenantIdentifier>1</TenantIdentifier>
  </ProductInformation>
  <BreakUpInformation>
    <ProductConsumption>
      <ConsumptionPattern>
        <Consumption>
          <Duration>
            <From>Not-Specified</From>
            <Till>Mon, 27 Feb 2012 04:44:46 000</Till>
          </Duration>
          <Value>15000</Value>
          <TotalRecords>1</TotalRecords>
        </Consumption>
      </ConsumptionPattern>
    </ProductConsumption>
  </BreakUpInformation>
  <BreakUpInformation>
    <ProductConsumption>
      <ConsumptionPattern>
        <Consumption>
          <Duration>
            <From>Not-Specified</From>
            <Till>Mon, 27 Feb 2012 04:44:45 000</Till>
          </Duration>
          <Value>0</Value>
          <TotalRecords>1</TotalRecords>
        </Consumption>
      </ConsumptionPattern>
    </ProductConsumption>
  </BreakUpInformation>
</BriefBillingInformation>
   

ClosedDetailed Billing

                
<emsResponse> <stat>ok</stat> <!--This is an automated/formatted XML output for the queried ISV aggregation information.--> <DetailedBillingInformation> <ProductInformation> <ProductName>Post</ProductName> <ProductVersion>1</ProductVersion> <ContractID>0134cdc6-fb1f-4494-aa8f-c0979857ddf0</ContractID> <TenantIdentifier>1</TenantIdentifier> </ProductInformation> <BreakUpInformation> <FeatureConsumption> <FeatureIdentifier>2</FeatureIdentifier> <FeatureName>Post_1</FeatureName> <ConsumptionPattern> <Consumption> <Duration> <From>Mon, 18 Nov 2013 07:11:25 000</From> <Till>Mon, 18 Nov 2013 07:41:25 000</Till> </Duration> <Value>1800000</Value> <TotalRecords>1</TotalRecords> </Consumption> <Consumption> <Duration> <From>Mon, 18 Nov 2013 07:09:12 000</From> <Till>Mon, 18 Nov 2013 07:41:25 000</Till> </Duration> <Value>1800000</Value> <TotalRecords>1</TotalRecords> </Consumption> </ConsumptionPattern> </FeatureConsumption> </BreakUpInformation> </DetailedBillingInformation> </emsResponse>

ClosedItemized Billing

<emsResponse>
  <stat>ok</stat>
  <!--This is an automated/formatted XML output for the queried ISV aggregation information.-->
  <ItemizedBillingInformation>
    <ProductInformation>
      <ProductName>Post</ProductName>
      <ProductVersion>1</ProductVersion>
      <ContractID>0134cdc6-fb1f-4494-aa8f-c0979857ddf0</ContractID>
      <TenantIdentifier>1</TenantIdentifier>
    </ProductInformation>
    <BreakUpInformation>
      <FeatureConsumption>
        <FeatureIdentifier>2</FeatureIdentifier>
        <FieldMajor>1</FieldMajor>
        <FeatureName>Post_1</FeatureName>
        <CustomerConsumption>
          <CustomerRefID>hcl</CustomerRefID>
          <IdentityConsumption>
            <IdentityName>c1</IdentityName>
            <ConsumptionPattern>
              <Consumption>
                <Duration>
                  <From>Mon, 18 Nov 2013 07:11:25 000</From>
                  <Till>Mon, 18 Nov 2013 07:41:25 000</Till>
                </Duration>
                <Value>1800000</Value>
                <TotalRecords>1</TotalRecords>
              </Consumption>
            </ConsumptionPattern>
          </IdentityConsumption>
          <IdentityConsumption>
            <IdentityName>null</IdentityName>
            <ConsumptionPattern>
              <Consumption>
                <Duration>
                  <From>Mon, 18 Nov 2013 07:09:12 000</From>
                  <Till>Mon, 18 Nov 2013 07:41:25 000</Till>
                </Duration>
                <Value>1800000</Value>
                <TotalRecords>1</TotalRecords>
              </Consumption>
            </ConsumptionPattern>
          </IdentityConsumption>
        </CustomerConsumption>
      </FeatureConsumption>
    </BreakUpInformation>
  </ItemizedBillingInformation>
</emsResponse>
 
See Also:

Output Format for Failure

Understanding Billing Response

The following table lists the meaning of tags used in the billing response:

Tag Description
ProductName Product name
ProductVersion Product version
ContractID Entitlement ID
TenantIdentifier Unique identifier assigned to an ISV
Duration Bill duration
Value Total feature usage count (sum of all sessions usage), in <From> and <Till> time span.
TotalRecords Number of sessions
FeatureIdentifier Feature ID
FeatureName Unique name of the feature
FieldMajor

Specifies if the feature is time-based or count-based.

  1. 1 : Time-based
  2. 2: Count-based
CustomerRefID Customer reference ID
IdentityName User ID

Error Codes

Error Code Description

100

Invalid request parameter.

101

You are not authorized to use this service.

120

{field} value is less than the minimum permitted value {value}. [Note: This error code is applicable for the fields - productd, featureId,entId, billType, lmId, lastModified, timeZoneId, customerId, and granularity.]

122

{field} is a required field and should have a not null value. [Note: This error code is applicable for the fields - Eid, namespaceName, featureName, startDate, endDate, userIds, featureId, productName, productVersion, detailsLM, lmId, templateType, customAttribute, lineItemId, customerRefId, granularity, loginId, oldPassword, and newPassword.]

123

endDate should be of dataType Date in the format yyyy-mm-dd startDate should be of dataType Date in the format yyyy-mm-dd.

128

You should log on first.

132 The URL address does not exist.

617

Start date cannot be greater than end date.

1015

Invalid bill type preference. Valid values are 1(Brief bill), 2(Detail bill),3(Itemized bill).

1017

Data Unavailable.

1081 Invalid Web service version provided
1084 No Web service version provided
1088 The EMS system is running on HTTPS. Please provide the correct Web service URL.