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.

Report Description
Billing View the activity of developers for a single billing month and verify that the rate plans have been applied correctly.
Prepaid Balance View the balance refills that a prepaid developer has made in a billing month or in a currently open month, so that you can reconcile with the payments received from your payment processor.
Revenue View activity and revenue generated by developers within a date range, so that you can analyze the performance of your API product bundles and products across your developers (and their applications).
Variance

Compare activity and revenue generated by developers in two date ranges, so that you can analyze upward or downward trends in the performance of your API packages and products across your developers (and their applications).

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.

Exploring the Monetization Reports page

Access the Monetization Reports page, as described below.

Edge

To access the Reports page using the Edge UI:

  1. Sign in to apigee.com/edge.
  2. Select Publish > Monetization > Reports in the left navigation bar.

The Reports page is displayed.

As highlighted in the figure, the Reports page enables you to:

Classic Edge (Private Cloud)

To access the Reports page using the Classic Edge UI:

  1. Sign in to http://ms-ip:9000, where ms-ip is the IP address or DNS name of the Management Server node.
  2. Select Monetization > Monetization Reports in the top navigation bar.

The Reports page is displayed.

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.

Edge

To configure a report using the Edge UI:

  1. Select Publish > Monetization > Reports in the left navigation bar.
  2. Click + Report
  3. Configure the report details defined in the following table.
    Field Description
    Name Unique name of the report.
    Description Description of the report.
    Report type See Types of monetization reports.
  4. Configure the remaining report details based on the report type selected, as described in the following sections:
  5. After you enter the information in the report window, you can:
    • Click Save report to save the report configuration.
    • For a Detailed report only, click Submit job to run the report asynchronously and retrieve the results at a later time. See Generating and downloading a report for more.

    • Click Save as CSV or Save as Zip to download the generated report to your local machine as a comma-separated values (CSV) or a compressed zip file containing the CSV. Zip downloads are recommended for large reports and will download more effectively.

Classic Edge (Private Cloud)

To create a report using the Classic Edge UI:

  1. Select Monetization > Monetization Reports in the top navigation bar.
  2. In the drop-down menu, select the type of report you want to create. See Types of monetization reports.
  3. Click + Report.
  4. Configure the report details based on the billing type selected, as described in the following sections:
  5. After you enter the information in the report window, you can:
    • Click Save as ... to save the report configuration and download the report later.
    • For a Detailed report only, click Submit job to run the report asnchronously and retrieve the results at a later time. See Generating and downloading a report for more.

    • Click Download CSV to generate and download the report to your local machine as a comma-separated values (CSV) file for viewing.

Configuring a billing report

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

Field Description
Billing Month

The billing month for the report.

Reporting Level

Reporting level. Valid values include:

  • Detailed: Displays each transaction on a separate line and allows you to check that rate plans have been applied correctly. There is no summary.
  • Summary: Summarizes the total revenues for each API product and developer.
Product Bundles

Note: In Classic Edge UI, API product bundles are referred to as API packages.

Select the API product bundles to include in the report. If none are selected, all API product bundles are included in the report.

The report includes a separate line for each selected API product bundles.

For a summary report, you can optionally check Do not display in the Summary display options. In this case, the report aggregates information across all (or selected) API product bundles (and does not list information for each API product bundles separately).

Products

Select the API products to include in the report. If none are selected, all API products are included in the report.

The report includes a separate line for each selected API product.

For a summary report, you can optionally check Do not display in the Summary display options. In this case, the report aggregates information across all (or selected) developers (and does not list information for each selected developer separately).

Companies

Select the companies to include in the report. If none are selected, all companies are included in the report.

Rate Plan

Rate plans to include in the report. Select one of the following:

  • All rate plans: Include all rate plans in the report.
  • Standard rate plans: Include only standard rate plans in the report.
  • Developer-specific rate plans: Include only developer plans in the report.

Configuring a prepaid balance report

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

Field Description
Billing Month

The billing month for the report.

Reporting Level

Reporting level. Valid values include:

  • Detailed: Displays each balance refill separately and allows you to reconcile with payments received from your payment processor.
  • Summary: Summarizes the total balance refills for each developer.
Companies

Select the companies to include in the report. If none are selected, all companies are included in the report.

Configuring a revenue report

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

Field Description
Date Range

Range of dates for the report. Select one of the following:

  • Preset: Select one of the standard date ranges (such as Last Calendar Month) from the drop-down menu.
  • Custom: Choose a start date and an end date for the range from the calendar pop-up.
Select currency

Currency for the report. Valid values include:

  • Local currency: Each line of the report is displayed using the applicable rate plan. This means that there may be multiple currencies in one report if the developers have plans that use different currencies.
  • Euro: Local currency transactions in the report are converted and displayed in Euros.
  • United Kingdom Pound: Local currency transactions in the report are converted and displayed in pounds.
  • United States Dollars: The local currency transactions in the report are converted and displayed in dollars.
Reporting Level

Reporting level. Valid values include:

  • Detailed: Displays each transaction on a separate line. There is no summary.
  • Summary: Summarizes the total revenues for each API product and developer, depending on the parameters that you select.
Product Bundles

Note: In Classic Edge UI, API product bundles are referred to as API packages.

Select the API product bundles to include in the report. If none are selected, all API product bundles are included in the report.

The report includes a separate line for each selected API product bundles.

For a summary report, you can optionally check Do not display in the Summary display options. In this case, the report aggregates information across all (or selected) API product bundles (and does not list information for each API product bundles separately).

Products

Select the API products to include in the report. If none are selected, all API products are included in the report.

The report includes a separate line for each selected API product.

For a summary report, you can optionally check Do not display in the Summary display options. In this case, the report aggregates information across all (or selected) developers (and does not list information for each selected developer separately).

Companies

Select the companies to include in the report. If none are selected, all companies are included in the report.

For a summary report, you can optionally check Do not display in the Summary Display Options section. In this case, the report aggregates information across all (or selected) companies (and does not list information for each selected company separately).

Apps

Select the applications to include in the report. If none are selected, all applications are included in the report.

The report includes a separate line for each selected application.

For a summary report, you can optionally check Do not display in the Summary Display Options section. In this case, the report aggregates information across all (or selected) applications (and does not list information for each selected application separately).

Summary display options

Order in which columns are grouped and displayed in the report. Select a number that indicates the relative order of that section in the grouping (1 is the first grouping). For example, the following groups the report first by packages, then by products, then by developers, then by applications.

If you don’t want to display a section, select Do not display, then select the remaining fields in order. The order automatically updates when you change the relative order of one section or choose not to display a section in the report.

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:

Field Description
Date Range

Range of dates for the report. Select one of the following:

  • Preset: Select one of the standard date ranges (such as Last Calendar Month) from the drop-down menu.
  • Custom: Choose a start date and an end date for the range from the calendar pop-up.
Packages

The API packages to include in the report. Select one of the following:

  • All: Includes all API packages in the report.
  • Selected: Displays a list from which you can select the API packages to include in the report. If you select no packages, all packages are included in the report.

The report includes a separate line for each selected API package.

For a summary report, you can optionally check Don't Display (Packages) in the Summary Display Options section. In this case, the report aggregates information across all (or selected) API packages (and does not list information for each API package separately).

Products

The API products to include in the report. Select one of the following:

  • All: Includes all API products in the report.
  • Selected: Displays a list from which you can select the products to include in the report. If you select no products, all products are included in the report.

The report includes a separate line for each selected API product.

For a summary report, you can optionally check Don't Display (Products) in the Summary Display Options section. In this case, the report aggregates information across all (or selected) API products (and does not list information for each API product separately).

Companies

The companies to include in the report. Select one of the following:

  • All: Includes all companies in the report.
  • Selected: Displays a list from which you can select the companies to include in the report. If you select no companies, all companies are included in the report.

The report includes a separate line for each selected company.

For a summary report, you can optionally check Don't Display (Companies) in the Summary Display Options section. In this case, the report aggregates information across all (or selected) companies (and does not list information for each selected company separately).

Apps

The applications to include in the report. Select one of the following:

  • All: Includes all applications in the report.
  • Selected: Displays a list from which you can select the applications to include in the report. If you select no applications, all applications are included in the report.

The report includes a separate line for each selected application.

For a summary report, you can optionally check Don't Display (Applications) in the Summary Display Options section. In this case, the report aggregates information across all (or selected) applications (and does not list information for each selected application separately).

Currency

Currency for the report. Valid values include:

  • Local currency: Each line of the report is displayed using the applicable rate plan. This means that there may be multiple currencies in one report if the developers have plans that use different currencies.
  • EUR: Local currency transactions in the report are converted and displayed in Euros.
  • GPB: Local currency transactions in the report are converted and displayed in pounds.
  • USD: The local currency transactions in the report are converted and displayed in dollars.
Summary display options

Order in which columns are grouped and displayed in the report. Select a number that indicates the relative order of that section in the grouping (1 is the first grouping). For example, the following groups the report first by packages, then by products, then by developers, then by applications.

If you don’t want to display a section, select Do not display, then select the remaining fields in order. The order automatically updates when you change the relative order of one section or choose not to display a section in the report.

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 CSV file icon icon or the zip file icon 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:

        Disk image appears when 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:

Query Parameter Description
all Flag that specifies whether to return all API product bundles. If set to false, the number of API product bundles returned per page is defined by the size query parameter. Defaults to false.
size Number of API product bundles returned per page. Defaults to 20. If the all query parameter is set to true, this parameter is ignored.
page Number of the page that you want to return (if content is paginated). If the all query parameter is set to true, this parameter is ignored.
sort Field by which to sort information. If the all query parameter is set to true, this parameter is ignored. Defaults to UPDATED:DESC.

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
In addition, you can generate a revenue report for a specific developer, as described in Generate a revenue report for a developer.

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:

Resource Returns
/organizations/{org_name}/applications-with-transactions

Applications with transactions

/organizations/{org_name}/developers-with-transactions

Developers with transactions

/organizations/{org_name}/products-with-transactions

Products with transactions

/organizations/{org_name}/packages-with-transactions

API product bundles (or API packages) with transactions

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:

Name Description Default Required?
name

The name of the report.

N/A Yes
description

A description of the report.

N/A No
mintCriteria

The criteria for configuring a report. See Criteria configuration options for further details.

N/A No
type

The type of the report. The value can be one of the following:

  • BILLING
  • REVENUE
  • VARIANCE
  • PREPAID_BALANCE
N/A Yes

Criteria configuration options

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

Name Description Default Required?
appCriteria

ID and organization for a specific application to be included in the report. If this property is not specified, all applications are included in the report.

N/A No
billingMonth

Note: This property is not valid for revenue reports.

Billing month for the report, such as JULY.

N/A Yes
billingYear

Note: This property is not valid for revenue reports.

Billing year for the report, such as 2015.

N/A Yes
currCriteria

ID and organization for a specific currency to be included in the report. If this property is not specified, all supported currencies are included in the report.

N/A No
currencyOption

Currency for the report. Valid values include:

  • LOCAL. Each line of the report is displayed using the applicable rate plan. This means that there may be multiple currencies in one report if the developers have plans that use different currencies.
  • EUR. Local currency transactions are converted and displayed in Euros.
  • GPB. Local currency transactions are converted and displayed in United Kingdom pounds.
  • USD. Local currency transactions are converted and displayed in United States dollars.
N/A No
devCriteria

Developer ID (email address), and organization name for a specific developer to be included in the report. If this property is not specified, all developers are included in the report. For example:

"devCriteria":[{
    "id":"RtHAeZ6LtkSbEH56",
    "orgId":"my_org"}
]
                
N/A No
devCustomAttributes

Note: This property applies only to revenue reports.

Custom attributes to include in the report, if defined for a developer. For example:

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

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

N/A No
fromDate

Note: This property applies only to revenue, variance, and transaction activity reports.

Starting date of the report in UTC.

N/A Required for revenue reports; not required for other report types.
groupBy

Order in which columns are grouped in the report. Valid values include:

  • APPLICATION
  • BALANCE
  • DEVELOPER
  • ORG
  • PACKAGE
  • PRODUCT
  • RATEPLAN
N/A No
monetizationPackageId

ID of one or more API product bundles to include in the report. If this property is not specified, all API product bundles are included in the report.

Note: This property is not valid when viewing the transaction activity (/transaction-search).

N/A No
pkgCriteria

ID and organization for a specific API product bundle to be included in the report. If this property is not specified, all API product bundles are included in the report. This property can be specified instead of the monetizationpackageIds property.

Note: This property is not valid when viewing the transaction activity (/transaction-search).

N/A No
prevFromDate

Note: This property applies only to variance reports.

Starting date of a previous period in UTC. Used to create a report for a previous period for comparison against a current report.

N/A No
prevToDate

Note: This property applies only to variance reports.

Ending date of a previous period in UTC. Used to create a report for a previous period for comparison against a current report.

N/A No
prodCriteria

ID and organization for a specific API product to be included in the report. If this property is not specified, all API products are included in the report. This property can be specified instead of the productIds property.

Note: This property is not valid when viewing the transaction activity (/transaction-search).

N/A No
productIds

ID of one or more API products to include in the report. If this property is not specified, all API products are included in the report.

API product IDs should be specified as org-name@@@product-name. For example: "productIds": ["myorg@@@myproduct", "myorg@@@myproduct2"]

N/A No
pricingTypes

Pricing type of rate plan to be included in the report. Valid values include:

  • REVSHARE. Revenue share plan.
  • REVSHARE_RATECARD. Revenue share and rate card rate plan.
  • RATECARD. Rate card plan.

If this property is not specified, rate plans of all pricing types are included in the report.

N/A No
ratePlanLevels

Type of rate plan to be included in the report. Valid values include:

  • DEVELOPER. Developer rate plan.
  • STANDARD. Standard rate plan.

If this property is not specified, both developer-specific and standard rate plans are included in the report.

N/A No
showRevSharePct

Flag that specifies whether the report shows revenue share percentages. Valid values include:

  • true. Show revenue share percentages.
  • false. Do not show revenue share percentages.
N/A No
showSummary

Flag that specifies whether the report is a summary. Valid values include:

  • true. Report is a summary.
  • false. Report is not a summary.
N/A No
showTxDetail

Note: This property applies only to revenue reports.

Flag that specifies whether the report shows transaction level details. Valid values include:

  • true. Show transaction-level details.
  • false. Do not show transaction-level details.
N/A No
showTxType

Flag that specifies whether the report shows the type of each transaction. Valid values include:

  • true. Show the type of each transaction.
  • false. Do not show the type of each transaction.
N/A No
toDate

Note: This property applies only to revenue, variance, and transaction activity reports.

End date of the report in UTC.

The report includes data collected up to the end of day before the date specified. Report data collected on the specified end date will be excluded from the report. If you want to expire a rate plan on December 31, 2016, for example, you should set the toDate value to 2017-01-01. In this case, the report will include report data up to the end of the day on December 31, 2016; report data on January 1, 2017 will be excluded.

N/A Required for revenue reports; not required for other report types.
transactionStatus

Status of transactions to include in the report. Valid values include:

  • SUCCESS. Successful transaction.
  • DUPLICATE. Duplicate transaction. These transactions can be ignored. The data pipeline from the Apigee runtime to the rating server can sometimes generate duplicate transactions in order to be fault tolerant and monetization recognizes and marks them as duplicate.
  • FAILED. Failed transaction. This status is triggered when the validation of a precondition fails. For example:
    • Rating attempted even though the developer has not purchased rate plan. This can occur if the Monetization Limits Check policy is not configured.
    • Quota is exceeded, but calls still continue. This can occur if the Monetization Limits Check policy is not configured.
    • Negative custom attribute value was sent for custom attribute-based plan.
  • INVALID_TSC. Transaction is invalid. This status is triggered when the txProviderStatus runtime criteria does not match the success criteria specified at the API product bundle-level.
  • REVIEW. Transactions requiring review. This status is triggered for flexible revenue share rate plans if the value falls within a revenue range that is not configured.
N/A No
transactionCustomAttributes

Custom transaction attributes to include in summary revenue reports. You must enable this feature in your organization. See Including custom transaction attributes in revenue summary reports.

N/A No
transactionTypes

Type of transactions to be included in the report. Valid values include:

If this property is not specified, all transaction types are included in the report.

N/A No