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.
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.
Edge
To access the Reports page using the Edge UI:
- Sign in to apigee.com/edge.
- 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:
- View summary information for all reports, including name and description, report type and date range, and last modified date
- Configure a report
- Generate and download a report in CSV or zip file format
- Edit a report
- Delete a report
- Search the list of reports
Classic Edge (Private Cloud)
To access the Reports page using the Classic Edge UI:
- Sign in to
http://ms-ip:9000, where ms-ip is the IP address or DNS name of the Management Server node. - Select Monetization > Monetization Reports in the top navigation bar.
The Reports page is displayed.
- View the current list of reports
- Configure a report
- Generate and download a report in CSV format
- Edit a report
- Delete a report
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:
- Select Publish > Monetization > Reports in the left navigation bar.
- Click + Report
- 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. - Configure the remaining report details based on the report type selected, as described in the following sections:
- 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:
- Select Monetization > Monetization Reports in the top navigation bar.
- In the drop-down menu, select the type of report you want to create. See Types of monetization reports.
- Click + Report.
- Configure the report details based on the billing type selected, as described in the following sections:
- 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:
|
| 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:
|
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:
|
| 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:
|
| Select currency |
Currency for the report. Valid values include:
|
| Reporting Level |
Reporting level. Valid values include:
|
| 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">["partner_id","tax_source"]</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_idandtax_sourcecustom 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:
|
| Packages |
The API packages to include in the report. Select one of the following:
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:
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:
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:
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:
|
| 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:
- Access the Reports page.
- Position the cursor over the report you want to download.
Under the Modified column, click either:
- The
icon or the 
icon (for a Summary report). The report is saved to a CSV or zip file synchronously. - Submit job (for a Detailed report). The asynchronous job starts.
Monitor the status of the job in the Modified column.
The disk icon appears when the report is ready for download:
- After the job has completed, click disk icon to download the report.
- The
The following provides an example of a CSV file for a summary billing report.
Editing a report
To edit a report:
- Access the Reports page.
- Position the cursor over the report you want to edit and click
in the actions menu. - Update the report configuration, as required.
- Click Update report to save the updated report configuration.
Deleting a report
To delete a report:
- Access the Reports page.
- Position the cursor over the report that you want to delete.
- 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-reportsrevenue-reportsprepaid-balance-reportsvariance-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:
| 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:
|
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:
|
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 |
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:
|
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 ( |
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 Note: This property is not valid when viewing the transaction activity ( |
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 Note: This property is not valid when viewing the transaction activity ( |
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 |
N/A | No |
pricingTypes |
Pricing type of rate plan to be included in the report. Valid values include:
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:
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:
|
N/A | No |
showSummary |
Flag that specifies whether the report is a summary. Valid values include:
|
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:
|
N/A | No |
showTxType |
Flag that specifies whether the report shows the type of each transaction. Valid values include:
|
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:
|
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 |