Send Docs Feedback

Create reports

Introduction

Monetization includes extensive reporting facilities. You can generate any of the following reports:

  • Billing. This report allows you to view the activity of developers for a single billing month, and allows you to check that the rate plans have been applied correctly before you generate your billing documents.
  • Prepaid Balance. This report allows you to 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. This report allows you to view activity and revenue generated by developers within a date range, so that you can analyze the performance of your API packages and products across your developers (and their applications).
  • Variance. This report allows you to 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).

You can also make adjustments to these records as necessary.

In addition, you can get more focused usage information about transaction activity. In particular, you can determine which applications, developers, API packages, or API products, had transaction activity in a given date range.

Toolbox

You can create reports using the management UI or monetization API.

If you use the UI, you create a report on the Monetization Reports page.

If you use the API, you first create a report definition for the organization by issuing a POST request to the /organizations/{org_name}/report-definitions resource

. You can also create a report definition for a specific developer by issuing a POST request to /organizations/{org_name}/developers/{dev_id}/report-definitions resource. You then generate the report by issuing a POST request to the organizations/{org_id}/{report_type} resource, where {report_type} specifies the type of report you want to generate.

Creating a report using the UI

  1. Select Monetization > Monetization Reports in the management UI.

    This opens the Monetization Reports page.

  2. In the drop-down menu, select the type of report you want to create. Select from the following:
    • Billing. This report allows you to view the activity of developers for a single billing month, and allows you to check that the rate plans have been applied correctly before you generate your billing documents. See Creating a billing report for setup details.
    • Prepaid Balance. This report allows you to 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. See Creating a prepaid balance report for setup details.
    • Revenue. This report allows you to view activity and revenue generated by developers within a date range, so that you can analyze the performance of your API packages and products across your developers (and their applications). See Creating a revenue report for setup details.
    • Variance. This report allows you to 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). See Creating a variance report for setup details.
  3. Click +Report.

    This opens a Billing Report window, Prepaid Balance Report window, Revenue Report window, or Variance Report window, as appropriate, for you to create the specific report.

Creating a billing report

To create a billing report, enter the following information in the Billing Report window:

Field Description
Billing Month

The billing month for the report.

Reporting Level

Whether this is a summary report or a detailed report. Select one of the following:

  • Summary Report. This report summarizes the total revenues for each API product and developer.
  • Detailed Report. This report displays each transaction on a separate line and allows you to check that rate plans have been applied correctly. There is no summarization.

    CHARGE transactions are not included in Detailed reports because of the potentially large number transactions.

Packages

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

  • All. This includes all API packages in the report.
  • Selected. This 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. 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. This includes all API products in the report.
  • Selected. This 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. In this case, the report aggregates information across all (or selected) developers (and does not list information for each selected developer separately).

Companies

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

  • All. This includes all companies in the report.
  • Selected. This displays a list from which you can select the companies include in the report. If you select no companies, all companies are included in the report.
Rate Plan

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

  • All Rate Plans. Includes all rate plans in the report.
  • Standard Rate Plans. Includes only standard rate plans in the report.
  • Developer-Specific Rate Plans. Includes only developer plans in the report.

Creating a prepaid balance report

To create a prepaid balance report, enter the following information in the Prepaid Balance Report window:

Field Description
Billing Month

The billing month for the report.

Reporting Level

Whether this is a summary report or a detailed report. Select one of the following:

  • Summary Report. This report summarizes the total balance refills for each developer.
  • Detailed Report. This report displays each balance refill separately and allows you to reconcile with payments received from your payment processor.
Companies

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

  • All. This includes all companies in the report.
  • Selected. This displays a list from which you can select the companies include in the report. If you select no companies, all companies are included in the report.

Creating a revenue report

To create a revenue report, enter the following information in the Revenue Report window:

Field Description
Date Range

The range of dates for the report. Select one of the following:

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

Whether this is a summary report or a detailed report. Select one of the following:

  • Summary Report. This report summarizes the total revenues for each API product and developer, depending on the parameters that you select.
  • Detailed Report. This report displays each transaction on a separate line. There is no summarization.

    CHARGE transactions are not included in Detailed reports because of the potentially large number transactions.

Packages

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

  • All. This includes all API packages in the report.
  • Selected. This 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. This includes all API products in the report.
  • Selected. This 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. This includes all companies in the report.
  • Selected. This 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).

Applications

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

  • All. This includes all applications in the report.
  • Selected. This 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

The currency for the report. Select one of the following:

  • 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. The local currency transactions in the report are converted and displayed in Euros.
  • GPB. The 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.

If you select EUR, GBP or USD, the report displays all transactions using that single currency, based on the exchange rate in effect on the date of the transaction.

Summary Display Options

The order in which sections 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 "Don’t 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. Enable this reporting feature by adding a MINT.SUMMARY_CUSTOM_ATTRIBUTES property to your organization and indicating which custom attributes are added to the monetization database tables.

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

If you're a cloud customer, contact Apigee Support to enable the property. If you're an Apigee Edge for Private Cloud customer, set the flag using the following API PUT call 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.

When you update the organization with the API call, be sure to include all the existing organization properties in the payload. If you don't, all existing organization properties are overwritten by only the properties you set with this call.

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 settings.

Creating a variance report

To create a variance report, enter the following information in the Variance Report window:

Field Description
Date Range

The two ranges of dates for the report. Enter a date range in both of the following fields:

  • Current. Choose a start date and an end date for the range from the calendar pop-up.
  • Prior. Choose a start date and an end date for the range from the calendar pop-up.

The report compares activity and revenue generated in the current date range with the prior date range.

Packages

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

  • All. This includes all API packages in the report.
  • Selected. This 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. This includes all API products in the report.
  • Selected. This 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. This includes all companies in the report.
  • Selected. This 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).

Applications

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

  • All. This includes all applications in the report.
  • Selected. This 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

The currency for the report. Select one of the following:

  • 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. The local currency transactions in the report are converted and displayed in Euros.
  • GPB. The 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.

If you select EUR, GBP or USD, the report displays all transactions using that single currency, based on the exchange rate in effect on the date of the transaction.

Summary Display Options

The order in which sections 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 "Don’t 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.

Saving or downloading reports using the UI

After you enter the information in the Billing Report, Prepaid Balance Report, Revenue Report, or Variance Report window, you can either save the report configuration or download the generated report to your local machine as a comma-separated values (CSV) file for viewing.

To save a report configuration: Click Save As as at the bottom of the Billing Report, Prepaid Balance Report, Revenue Report, or Variance Report window to give the report a name and description.

The report configuration is then added to the Saved Reports section of the Monetization Reports page, in its appropriate category: Billing, Prepaid Balance, Revenue, or Variance.

You can then edit the configuration, as needed.

To edit a saved report configuration:

  1. Select the report in the Saved Reports section of the Monetization Reports page.

    This opens the Billing Report, Prepaid Balance Report, Revenue Report, or Variance Report window, as appropriate.

  2. Update the report configuration, as needed.
  3. Click Save As to save the updated report configuration.

If you save the updated report, it will be added to the Saved Reports list on the Reports page (in the appropriate report category). Saving the updated version does not overwrite the previous version. You should delete the old version if it is no longer required.

To download a generated report to a CSV file: Click Download CSV in the Billing Report, Prepaid Balance Report, Revenue Report, or Variance Report window. If you saved the report configuration, you can also download a generated report by clicking Download CSV in the Report Actions column for the report in the Saved Reports section of the Reports page.

Here is an example of a CSV file for a summary billing report.

Deleting reports in the UI

To delete a report, click Delete in the row for the report in the Saved Reports section of the Monetization Reports page. You will be prompted to confirm the deletion.

Creating a report definition using the API

Before you can generate a report, you create a report definition that configures the report.

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

To create a report definition 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, 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 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 definition configuration settings 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 package 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 sections in the report will be grouped in the following order: PACKAGE, PRODUCT, DEVELOPER, APPLICATION.

$ 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",
         "toDate":"2015-07-31",
         "showTxDetail":true,
         "showSummary":true,
         "transactionTypes":[
            "PURCHASE",
            "CHARGE",
            "REFUND",
            "CREDIT",
            "SETUPFEES",
            "TERMINATIONFEES",
            "RECURRINGFEES"
         ],
         "monetizationPackageIds":[
            "payment"
         ],
         "productIds":[
            "payment"
         ],
         "currencyOption":"LOCAL",
         "groupBy":[
            "PACKAGE",
            "PRODUCT",
            "DEVELOPER",
            "APPLICATION"
         ]
      }
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/report-definitions" \
-u myname:mypass

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":"{org_name}"}]
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/5cTWgdUvdr6JW3xU/report-definitions" \
-u myname:mypass

Retrieving report definitions using the API

You can retrieve a specific report definition or all report definitions for an organization. You can also retrieve report definitions for an individual developer.

To retrieve a specific report definition 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 definition (the ID is returned in the response when you create the report definition). 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 myname:mypass

To retrieve all the report definition for the organization, issue a GET request to /organizations/{org_name}/report-definitions. When you make the request, you can specify query parameters that limit the retrieval to a subset of the report definitions. You can also sort the results based on sorting criteria.

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

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

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" ],
      "monetizationPackageIds" : [ "payment" ],
      "productIds" : [ "payment" ],
      "showRevSharePct" : false,
      "showSummary" : true,
      "showTxDetail" : true,
      "showTxType" : false,
      "toDate" : "2015-07-31 00:00: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 retrieve the report definitions 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 query parameters that limit the retrieval to a subset of the report definitions. You can also sort the results based on sorting criteria.

For example, the following retrieves report definitions 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 myname:mypass

Updating a report definition using the API

To update a report definition, issue a PUT request to /organizations/{org_name}/report-definitions/{report_definition_id}, where {report_definition_id} is the identification of the specific report definition. When you make the update, you need to specify in the request body the updated settings and the ID of the report definition. 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 myname:mypass

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 definition using the API

To delete a report definition, issue a DELETE request to /organizations/{org_namer}/report-definitions/{report_definition_id}, where {report_definition_id} is the identification of the report definition 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 myname:mypass

Generating a report using the API

After you create a report definition, 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. 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",
      "toDate":"2015-07-31",
      "showTxDetail":true,
      "showSummary":true,                
      "transactionTypes":[
        "PURCHASE",
        "CHARGE",
        "REFUND",
        "CREDIT",
        "SETUPFEES",
        "TERMINATIONFEES",
        "RECURRINGFEES"
      ],
      "currencyOption":"LOCAL",
      "groupBy":[
        "PACKAGE",
        "PRODUCT",
        "DEVELOPER",
        "APPLICATION"]
 }' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/revenue-reports" \
-u myname:mypass

If found, the revenue report is generated in CSV file format. The report should look something like this:

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,Currency,Transaction Type,Provider Status,Total Volume,Charged Rate,
Location,location,N/A,,Apigee,QQ7uxeMGf3w9W08B,N/A,,USD,SETUPFEES,SUCCESS,1,15.0000,
Location,location,N/A,,BarCompany,barcompany,N/A,,USD,SETUPFEES,SUCCESS,1,15.0000,
Location,location,N/A,,fremont,fremont,N/A,,USD,SETUPFEES,SUCCESS,1,15.0000,
Location,location,N/A,,Juan's Taco Shack,juan-s-taco-sha,N/A,,USD,SETUPFEES,SUCCESS,1,15.0000,

Reporting transaction activity using the API

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

  • The identification of one or more API packages against which transactions were issued.
  • The identification of one or more API products against which transactions were issued.
  • The identification of one or more applications which issued transactions.
  • The identification of one or more developers who issued transactions.
  • The billing month and year in which to retrieve transactions.

See Criteria configuration settings for a complete list of criteria.

For example, the following retrieves 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,
    "developerCriteria": {
      "id": "dev7"
    }   
}'
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/transactions \
-u myname:mypass

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

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

Resource Retrieves
/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 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 retrieves 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 myname:mypass

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 definition configuration settings for the API

The following report definitions configuration options are exposed to the API:

Name Description Default Required?
name

The name of the report definition.

N/A Yes
description

A description of the report definition.

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
mintCriteria

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

N/A No

Criteria configuration settings

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

Name Description Default Required?
productIds

The identification 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.

N/A No
monetizationPakageId

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

N/A No
developerCriteria

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

N/A No
appCriteria

Specifies the 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
prodCriteria

Specifies the 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.

N/A No
pkgCriteria

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

N/A No
currCriteria

Specifies the 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
billingMonth

The billing month for the report, such as JULY.

N/A Yes
billingYear

The billing year for the report, such as 2015.

N/A Yes
transactionStatus

Indicates that transactions of the specified status will be included in the report. The value can be one or more of the following:

  • SUCCESS. Successful transactions.
  • FAILED. Failed transaction.
  • FINAL. Transactions marked as final.
  • REVIEW. Transaction marked as under review.

 

N/A No
types

The type of transactions to be included in the report. The value can be one or more of the following:

  • PURCHASE
  • CHARGE
  • REFUND
  • CREDIT
  • BALANCE
  • SETUPFEES
  • TERMINATIONFEES
  • RECURRINGFEES
  • TRUEUP. These are transactions that are used to readjust rated transactions. They are invoked when tax changes are made in the previous billing month.

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

N/A No
ratePlanLevels

The type of rate plan to be included in the report. The value can be one or more of the following:

  • 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
pricingTypes

The pricing type of rate plan to be included in the report. The value can be one or more of the following:

  • 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
showSummary

Indicates whether the report is a summary. The value can be one of the following:

  • true. The report is a summary.
  • false. The report is not a summary.
N/A No
showTxType

Indicates whether the report shows the type of each transaction. The value can be one of the following:

  • true. The report shows the type of each transaction.
  • false. The report does not show the type of each transaction.
N/A No
showRevSharePct

Indicates whether the report shows revenue share percentages. The value can be one of the following:

  • true. The report shows revenue share percentages.
  • false. The report does not show revenue share percentages.
N/A No
showTxDetail

This property applies only to revenue reports. Indicates whether the report shows transaction level details. The value can be one of the following:

  • true. The report shows transaction level details.
  • false. The report does not show transaction level details.
N/A No
fromDate

This property applies only to revenue and variance reports. The starting date of the report.

N/A No
toDate

This property applies only to revenue and variance reports. The ending date of the report.

N/A No
prevFromDate

This property applies only to variance reports. The starting date of a previous period. Used to create a report for a previous period for comparison against a current report.

N/A No
prevToDate

This property applies only to variance reports. The ending date of a previous period. Used to create a report for a previous period for comparison against a current report.

N/A No
groupBy

The order in which sections are grouped in the report. The value can be one or more of the following:

  • BALANCE
  • PACKAGE
  • PRODUCT
  • DEVELOPER
  • APPLICATION
  • ORG
N/A No
currencyOption

The currency for the report. The value can be one of the following:

  • 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. The local currency transactions in the report are converted and displayed in Euros.
  • GPB. The local currency transactions in the report are converted and displayed in United Kingdom pounds.
  • USD. The local currency transactions in the report are converted and displayed in United States dollars.

If you select EUR, GBP or USD, the report displays all transactions using that single currency, based on the exchange rate in effect on the date of the transaction.

N/A No
transactionCustomAttributes

This property includes custom transaction attributes in summary revenue reports. You must enable this feature in your organization. See Including custom transaction attributes in revenue summary reports.

N/A No

Next steps

See Create billing documents and learn how to generate invoices and other billing documents.

Help or comments?

  • If something's not working: Ask the Apigee Community or see Apigee Support.
  • If something's wrong with the docs: Click Send Docs Feedback on this page.
    (Incorrect? Unclear? Broken link? Typo?)