Manage reports

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

Introduction

Monetization reports enable you to access focused usage information and transaction activity. For example, you can determine which applications, developers, API product bundles, or API products had transaction activity for a given date range. With monetization, you can generate summary or detailed reports that track API usage.

Types of monetization reports

You can generate the following types of monetization reports.

About data retention

In Apigee Edge public cloud, monetization data retention is a plan entitlement. See the monetization entitlements at https://cloud.google.com/apigee/specsheets. Contact Apigee Sales if you want monetization data to be retained beyond the entitlement period. Extended data retention is activated at the time of request and cannot be retroactively activated to include data earlier than the original data retention window.

About duplicate transactions

If you compare monetization transaction reports with Analytics data, you might notice a small number of duplicate transactions. This is expected behavior as the monetization system can process several million transactions daily with many transactions processed in parallel at any given moment. On average, ~0.1% of transactions might be duplicates.

Exploring the Monetization Reports page

Access the Monetization Reports page, as described below.

Configuring a report

Configure a report using the UI, as described in the following sections.

Steps to configure a report

Configure a report using the Edge UI or Classice Edge UI.

Configuring a billing report

Follow the steps to configure a report and enter the following information in the report page:

Configuring a prepaid balance report

Configuring a revenue report

Follow the steps to configure a report and enter the following information in the report page:

Including custom transaction attributes in revenue summary reports

Transaction recording policies let you capture custom attribute data from transactions, and you can include those custom attributes in summary revenue reports. Define the default set of custom attributes included in the monetization database tables by setting the MINT.SUMMARY_CUSTOM_ATTRIBUTES property for your organization.

Using this feature requires some thought and planning, so review the considerations below.

If you're a cloud customer, contact Apigee Edge Support to set the property. If you're an Apigee Edge for Private Cloud customer, set the flag using a PUT request to the following API with System Administrator credentials.

curl -u email:password -X PUT -H "Content-type:application/xml" http://host:port/v1/o/{myorg} -d \
"<Organization type="trial" name="MyOrganization">
    <Properties>
        <Property name="features.isMonetizationEnabled">true</Property>
        <Property name="MINT.SUMMARY_CUSTOM_ATTRIBUTES">[&quot;partner_id&quot;,&quot;tax_source&quot;]</Property>
        <Property name="features.topLevelDevelopersAreCompanies">false</Property>
    </Properties>
</Organization>"

In this example, the API call enables the feature and adds partner_id and tax_source columns to the monetization database. Note that the array of custom attributes in the API call is URL-encoded.

Considerations for including custom transaction attributes in reports

• Be certain about the attribute names you want to use before you create them with the API. Those are column names in the database, and custom attribute data is always stored there.
• There are 10 available custom attribute slots in each transaction recording policy, as shown in the following image. Use the exact same attribute names and positions for the same attributes across the products that will be included in reports. For example, in the following transaction recording policy, the partner_id and tax_source custom attributes occupy boxes 4 and 5 respectively. This should be their name and position in all transaction recording policies for products to be included in reporting.
  
  

To include custom attributes in a summary revenue report after you enable the feature, use the report API by adding transactionCustomAttributes to the MintCriteria. See Criteria configuration options.

Configuring a variance report (Deprecated)

Follow the steps to configure a report and enter the following information in the report page:

Generating and downloading a report

After you create a report, you can then download the results of the report in CSV or zip file format. You can generate the CSV or zip file synchronously or asynchronously.

• For a synchronous report, you run the report request and the request is blocked until the analytics server provides a response. However, because a report might need to process a large amount of data (for example, 100's of GB), a synchronous report might fail because of a time out.

  A Summary report level only supports synchronous generation.

• For an asynchronous report, you run the report request and retrieve the results at a later time. Some situations when asynchronous query processing might be a good alternative include:

  • Analyzing and creating reports that span large time intervals.
  • Analyzing data with a variety of grouping dimensions and other constraints that add complexity to the query.
  • Managing queries when you find that data volumes have increased significantly for some users or organizations.

  A Detailed report level supports asynchronous generation.

To generate and download a report in CSV or zip file format, perform one of the following tasks:

1. Access the Reports page.
2. Position the cursor over the report you want to download.

3. Under the Modified column, click either:

   1. The icon or the icon (for a Summary report). The report is saved to a CSV or zip file synchronously.
   2. Submit job (for a Detailed report). The asynchronous job starts.

      1. Monitor the status of the job in the Modified column.

         The disk icon appears when the report is ready for download:

         
      2. After the job has completed, click disk icon to download the report.

The following provides an example of a CSV file for a summary billing report.

Editing a report

To edit a report:

1. Access the Reports page.
2. Position the cursor over the report you want to edit and click in the actions menu.
3. Update the report configuration, as required.
4. Click Update report to save the updated report configuration.

Deleting a report

To delete a report:

1. Access the Reports page.
2. Position the cursor over the report that you want to delete.
3. Click in the actions menu.

Managing monetization reports using the API

The following sections describe how to manage monetization reports using the API.

Configuring a report using the API

To configure a report for an entire organization, issue a POST request to /organizations/{org_name}/report-definitions.

To configure a report for a specific developer, issue a POST request to /organizations/{org_name}/developers/{dev_id}/report-definitions, where {dev_id} is the identification of the developer.

When you make the request, you need to specify the name and type of the report. The type is one of the following: BILLING, REVENUE, VARIANCE (deprecated), or PREPAID_BALANCE. In addition, you can specify criteria in the mintCriteria property that further configures the report. There are a wide range of criteria that you can specify. This gives you a lot of flexibility in configuring the report. Some of the things you can specify as criteria are:

• For a billing or prepaid balance report, the billing month for the report
• For a revenue report, the type of transactions covered in the report, such as, purchase transactions, charge transactions, and refunds
• For a prepaid balance report, the developer to whom the report applies
• For a revenue report, the API product bundles (or API packages), products, rate plans, and applications to which the report applies
• For a revenue or variance report, the applicable currency for the report
• For billing, prepaid balance, or revenue reports, whether the report is a summary report or a detailed report
• For a revenue summary report, include custom transaction attributes in the report

See Report configuration options for a complete list of report criteria.

For example, the following creates a revenue report that summarizes transaction activity for the month of July, 2015. The report includes a variety of transaction types specified in the transactionTypes property, and applies specifically to the Payment API product bundle and Payment API product. Because no specific developer or application is specified in the report definition, the report applies to all developers and applications. And because the currencyOption property is set to LOCAL, each line of the report will be displayed using the currency of the applicable rate plan. In addition, the groupBy property specifies that the columns in the report will be grouped in the following order: PACKAGE, PRODUCT, DEVELOPER, APPLICATION, and RATEPLAN (includes rate plan name and ID in the report).

$ curl -H "Content-Type: application/json" -X POST -d \
'{
      "name": "July 2015 revenue report",
      "description": " July 2015 revenue report for Payment product",
      "type": "REVENUE",     
      "mintCriteria":{
         "fromDate":"2015-07-01 00:00:00",
         "toDate":"2015-08-01 13:35:00",
         "showTxDetail":true,
         "showSummary":true,
         "transactionTypes":[
            "PURCHASE",
            "CHARGE",
            "REFUND",
            "CREDIT",
            "SETUPFEES",
            "TERMINATIONFEES",
            "RECURRINGFEES"
         ],
         "monetizationPackageIds":[
            "payment"
         ],
         "productIds":[
            "payment"
         ],
         "currencyOption":"LOCAL",
         "groupBy":[
            "PACKAGE",
            "PRODUCT",
            "DEVELOPER",
            "APPLICATION",
            "RATEPLAN"
         ]
      }
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/report-definitions" \
-u email:password

The following creates a detailed billing report that shows the activity of a developer DEV FIVE for June, 2015.

$ curl -H "Content-Type:application/json" -X POST -d \
'{
      "name": "June billing report, DEV FIVE",
      "description": "June billing report, DEV FIVE",
      "type": "BILLING",      
      "mintCriteria":{
         "billingMonth": "JUNE",
         "billingYear": 2015,
         "showTxDetail":true,
         "showSummary":false,         
         "currencyOption":"LOCAL"         
      },
      "devCriteria":[{
         "id":"RtHAeZ6LtkSbEH56",
         "orgId":"myorg"}]
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/5cTWgdUvdr6JW3xU/report-definitions" \
-u email:password

Viewing report configurations using the API

You can view a specific report configuration or all report configurations for an organization. You can also view report configurations for an individual developer.

To view a specific report configuration for an organization, issue a GET request to /organizations/{org_name}/report-definitions/{report_definition_id}, where {report_definition_id} is the identification of the specific report configuration (the ID is returned in the response when you create the report configuration). For example:

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/report-definitions/1f7fa53b-de5a-431d-9438-62131e1396c5" \
-u email:password

To view all the report configurations for the organization, issue a GET request to /organizations/{org_name}/report-definitions.

You can pass the following query parameters to filter and sort the results:

For example, the following returns report configurations for the organization and limits the retrieval to a maximum of five report configurations:

$ curl -H "Accept:application/json" -X GET \ 
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/report-definitions?size=5" \ 
-u email:password

The response should look something like this (only part of the response is shown):

{
  "reportDefinition" : [ {
    "description" : "Test revenue report",
    "developer" : null,
    "id" : "1f7fa53b-de5a-431d-9438-62131e1396c5",
    "lastModified" : "2015-08-27 15:44:03",
    "mintCriteria" : {
      "asXorg" : false,
      "currencyOption" : "LOCAL",
      "fromDate" : "2015-07-01 00:00:00",
      "groupBy" : [ "PACKAGE", "PRODUCT", "DEVELOPER", "APPLICATION", "RATEPLAN" ],
      "monetizationPackageIds" : [ "payment" ],
      "productIds" : [ "payment" ],
      "showRevSharePct" : false,
      "showSummary" : true,
      "showTxDetail" : true,
      "showTxType" : false,
      "toDate" : "2015-08-01 00:05:00",
      "transactionTypes" : [ "PURCHASE", "CHARGE", "REFUND", "CREDIT", "SETUPFEES", "TERMINATIONFEES", "RECURRINGFEES" ]
    },
    "name" : "Test revenue report",
    "organization" : {
      ...
    },
    "type" : "REVENUE"
  }, {
    "description" : "June billing report, DEV FIVE",
    "developer" : null,
    "id" : "fedac696-ce57-469b-b62c-a77b535fd0eb",
    "lastModified" : "2015-08-27 17:13:20",
    "mintCriteria" : {
      "asXorg" : false,
      "billingMonth" : "JUNE",
      "billingYear" : 2015,
      "currencyOption" : "LOCAL",
      "showRevSharePct" : false,
      "showSummary" : false,
      "showTxDetail" : true,
      "showTxType" : false
    },
    "name" : "June billing report, DEV FIVE",
    "organization" : {
      ...
    },
    "type" : "BILLING"
  } ],
  "totalRecords" : 2
}

To view the report configurations for a specific developer, issue a GET request to /organizations/{org_name}/developers/{dev_id}/report-definitions, where {dev_id} is the identification of the developer. When you make the request, you can specify the query parameters described above to filter and sort the data.

For example, the following returns report configurations for a specific developer and sorts the response by report name:

$ curl -H "Accept:application/json" -X GET \ 
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/5cTWgdUvdr6JW3xUreport-definitions?sort=name" \ 
-u email:password

Updating a report configuration using the API

To update a report configuration, issue a PUT request to /organizations/{org_name}/report-definitions/{report_definition_id}, where {report_definition_id} is the identification of the specific report configuration. When you make the update, you need to specify in the request body the updated configuration values and the ID of the report configuration. For example, the following request updates the report to a summary report (the updated properties are highlighted):

$ curl -H "Content-Type: application/json" -X PUT -d \
 '{
       "id": "fedac696-ce57-469b-b62c-a77b535fd0eb",
       "name": "June billing report, DEV FIVE",
       "description": "June billing report, DEV FIVE",
       "type": "BILLING",      
       "mintCriteria":{      
         "billingMonth": "JUNE",
         "billingYear": 2015,
         "showTxDetail":false,
         "showSummary":true    
        }     
 }' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/report-definitions/fedac696-ce57-469b-b62c-a77b535fd0eb" \
-u email:password

The response should look something like this (only part of the response is shown):

{
 "description" : "June billing report, DEV FIVE",
  "developer" : null,
  "id" : "fedac696-ce57-469b-b62c-a77b535fd0eb",
  "lastModified" : "2015-08-27 17:47:29",
  "mintCriteria" : {
    "asXorg" : false,
    "billingMonth" : "JUNE",
    "billingYear" : 2015,
    "showRevSharePct" : false,
    "showSummary" : true,
    "showTxDetail" : false,
    "showTxType" : false
  },
  "name" : "June billing report, DEV FIVE",
  "organization" : {
    ... 
  },
  "type" : "BILLING"
}

Deleting a report configuration using the API

To delete a report configuration, issue a DELETE request to /organizations/{org_namer}/report-definitions/{report_definition_id}, where {report_definition_id} is the identification of the report configuration to be deleted. For example:

$ curl -H "Accept:application/json" -X DELETE \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/report-definitions/fedac696-ce57-469b-b62c-a77b535fd0eb" \
-u email:password

Generating a report using the API

After you configure a report, you can generate the report in comma-separated values (CSV) file format for viewing.

To generate a report issue a POST request to organizations/{org_id}/{report_type}, where {report_type} specifies the type of report you want to generate. The types are:

• billing-reports
• revenue-reports
• prepaid-balance-reports
• variance-reports

For example, to generate a billing report, issue a POST request to organizations/{org_name}/billing-reports.

In the request body (for any type of report), specify search criteria for the report. Use mintCriteria properties to specify the search criteria. See Criteria configuration options for further details.

For example, the following request searches for a revenue report based on various criteria such as report start and end dates and transaction types.

$ curl -H "Content-Type:application/json" -H "Accept: application/octet-stream" -X POST -d \
'{
      "fromDate":"2015-07-01 00:00:00",
      "toDate":"2015-08-01 13:35:00",
      "showTxDetail":true,
      "showSummary":true,                
      "transactionTypes":[
        "PURCHASE",
        "CHARGE",
        "REFUND",
        "CREDIT",
        "SETUPFEES",
        "TERMINATIONFEES",
        "RECURRINGFEES"
      ],
      "currencyOption":"LOCAL",
      "groupBy":[
        "PACKAGE",
        "PRODUCT",
        "DEVELOPER",
        "APPLICATION",
        "RATEPLAN"]
 }' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/revenue-reports" \
-u email:password

If found, the revenue report is generated in CSV file format. The following provides an example of the report output:

Reporting Period:,From:,2015-07-01,  To:,2015-07-31
API Product:,All
Developer:,All
Application:,All
Currency:,Local
Type of Report:,Summary Revenue Report

Monetization Package,Package ID,API Product,Product ID,Developer Name,Developer ID,Application Name,Application ID,Rate Plan,Plan ID,Currency,Transaction Type,Provider Status,Total Volume,Charged Rate,
Location,location,foo_product,foo_product,Apigee,QQ7uxeMGf3w9W08B,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,
Location,location,foo_product,foo_product,BarCompany,barcompany,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,
Location,location,foo_product,foo_product,fremont,fremont,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,
Location,location,foo_product,foo_product,Juan's Taco Shack,juan-s-taco-sha,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,

Including developer custom attributes in revenue reports using the API

For revenue reports only, you can include custom attributes in the report, if the custom attribute is defined for the developer. You define custom attributes when adding developers to your organization, as described in Managing app developers.

To include custom attributes in a revenue report, issue a POST request to organizations/{org_name}/revenue-reports and include the devCustomAttributes array within the request body:

"devCustomAttributes": [
    "custom_attribute1",
    "custom_attribute2",
    ...
]

Note: Do not specify the predefined MINT_* and ADMIN_* attributes in the devCustomAttributes array.

For example, the following example includes three custom attributes, BILLING_TYPE, SFID, and ORG_EXT, in the report (if defined for the developer):

$ curl -H "Content-Type:application/json" -H "Accept: application/octet-stream" -X POST -d \
'{
      "fromDate":"2015-07-01 00:00:00",
      "toDate":"2015-08-01 13:35:00",
      "showTxDetail":true,
      "showSummary":true,                
      "transactionTypes":[
        "PURCHASE",
        "CHARGE",
        "REFUND",
        "CREDIT",
        "SETUPFEES",
        "TERMINATIONFEES",
        "RECURRINGFEES"
      ],
      "currencyOption":"LOCAL",
      "groupBy":[
        "PACKAGE",
        "PRODUCT",
        "DEVELOPER",
        "APPLICATION",
        "RATEPLAN"
      ],
      "devCustomAttributes": [
         "BILLING_TYPE",
         "SFID",
         "ORG_EXT"
      ]
 }' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/revenue-reports" \
-u email:password

The following provides an example of the report output that includes values for the two custom attributes:

Reporting Period:,From:,2015-07-01,  To:,2015-07-31
API Product:,All
Developer:,All
Application:,All
Currency:,Local
Type of Report:,Summary Revenue Report

Monetization Package,Package ID,API Product,Product ID,Developer Name,Developer ID,Application Name,Application ID,Rate Plan,Plan ID,Currency,Transaction Type,Provider Status,Total Volume,Charged Rate,BILLING_TYPE,SFID,ORG_EXT 
Location,location,foo_product,foo_product,Apigee,QQ7uxeMGf3w9W08B,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,PREPAID,123,3AA,
Location,location,foo_product,foo_product,BarCompany,barcompany,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,PREPAID,123,3AA,
Location,location,foo_product,foo_product,fremont,fremont,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,PREPAID,123,3AA,
Location,location,foo_product,foo_product,Juan's Taco Shack,juan-s-taco-sha,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,PREPAID,123,3AA,

Reporting transaction activity using the API

You can view the transaction activity for an organization by issuing a POST request to /organizations/{org_name}/transaction-search. When you make the request, you need to specify criteria for the retrieval. Some of the things you can specify as criteria are:

• ID of one or more API products for which transactions were issued.
• Billing month and year of the transactions.
• Developer(s) who issued the transaction.
• Type of the transaction like purchase and setupfees.
• Status of the transaction like success and failed.

See Criteria configuration options for a complete list of criteria.

For example, the following returns transactions issued by a specific developer for the billing month June, 2015:

$ curl -H "Content-Type:application/json" -X POST -d \
 '{        
    "billingMonth": "JUNE",
    "billingYear": 2015,
    "devCriteria": [{
      "id": "RtHAeZ6LtkSbEH56",
      "orgId":"myorg"}],
    "transactionTypes": ["PURCHASE", "CHARGE", "SETUPFEES"],
    "transactionStatus": ["SUCCESS", "FAILED"]
    }'
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/transaction-search \
-u email:password

You can also determine which applications, developers, API product bundles, or API products had transaction activity within a given date range. You view this information separately for each type of object. For example, you can view information specifically about applications that access APIs in your monetized API product bundles within a specified start and end date.

To view information about transaction activity, issue a GET request to one of the following resources:

When you issue the request, you need to specify as query parameters a start date and end date for the date range. For example, the following request returns developers with transactions during the month of August, 2015.

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers-with-transactions?START_DATE=2015-08-01&END_DATE=2015-08-31" \
-u email:password

The response should look something like this (only part of the response is shown):

{
  "developer" : [ {
    "address" : [ {
      "address1" : "Dev Five Address",
      "city" : "Pleasanton",
      "country" : "US",
      "id" : "0917f15f-9521-4e69-9376-07aa7b7b32ca",
      "isPrimary" : true,
      "state" : "CA",
      "zip" : "94588"
    } ],
    "approxTaxRate" : 0.0900,
    "billingType" : "POSTPAID",
    "broker" : false,
    "developerRole" : [ ],
    "email" : "dev5@myorg.com",
    "hasSelfBilling" : false,
    "id" : "tJZG6broTpGGGeLV",
    "legalName" : "DEV FIVE",
    "name" : "Dev Five",
    "organization" : {
      ...
    },
    "registrationId" : "dev5",
    "status" : "ACTIVE",
    "type" : "UNTRUSTED"
  }, {
    "address" : [ {
      "address1" : "Dev Seven Address",
      "city" : "Pleasanton",
      "country" : "US",
      "id" : "f86d8c9f-6ed1-4323-b050-6adf494096c9",
      "isPrimary" : true,
      "state" : "CA",
      "zip" : "94588"
    } ],
    "approxTaxRate" : 0.0900,
    "billingType" : "POSTPAID",
    "broker" : false,
    "developerRole" : [ ],
    "email" : "dev7@myorg.com",
    "hasSelfBilling" : false,
    "id" : "VI3l8m8IPAvJTvjS",
    "legalName" : "DEV SEVEN",
    "name" : "Dev Seven",
    "organization" : {
      ...
    },
    "registrationId" : "dev7",
    "status" : "ACTIVE",
    "type" : "UNTRUSTED"
  }, ...
  ]
}

Report configuration options for the API

The following report configuration options are available to the API:

Criteria configuration options

The following configuration options are available for reports through the mintCriteria property:

"devCriteria":[{
    "id":"RtHAeZ6LtkSbEH56",
    "orgId":"my_org"}
]
                

"devCustomAttributes": [
    "custom_attribute1",
    "custom_attribute2",
    ...
]