You're viewing **Apigee Edge** documentation. [Go to the **Apigee X** documentation](http://cloud.google.com/apigee/docs/api-platform/analytics/create-custom-reports). 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). > [!NOTE] > **Notes:** > - A revenue report includes data collected up to the end of day before the end date specified via the [`toDate`](https://docs.apigee.com/api-platform/monetization/create-reports#todate) configuration option. Report data collected on the specified end date will be excluded from the report. > - The **Developer Name** in a revenue report is the developer's *legal* name. You can configure the developer legal name using the `MINT_DEVELOPER_LEGAL_NAME` custom attribute, as described in [Configuring monetization attributes](https://docs.apigee.com/api-platform/publish/adding-developers-your-api-product#monetization-attributes). If the developer's legal name is not available, Apigee sets **Developer Name** to the developer's name (first name + last name). Suppose the developer's name is also not specified; Apigee sets the **Developer Name** to `NA`. | | Variance | > [!NOTE] > **Variance reports are [deprecated](https://docs.apigee.com/release/deprecation)** and can only be configured using the Classic Edge UI. Variance reports will be retired in a future release. 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 . 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: 1. Sign in to [apigee.com/edge](https://apigee.com/edge). 2. Select **Publish \> Monetization \> Reports** in the left navigation bar. The Reports page is displayed. ![](https://docs.apigee.com/static/api-platform/images/monetization-reports-zip-csv.png) 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](https://docs.apigee.com/api-platform/monetization/create-reports#configure) - [Generate and download a report](https://docs.apigee.com/api-platform/monetization/create-reports#download) in CSV or zip file format - [Edit a report](https://docs.apigee.com/api-platform/monetization/create-reports#edit) - [Delete a report](https://docs.apigee.com/api-platform/monetization/create-reports#delete) - Search the list of reports ### Classic Edge (Private Cloud) > [!NOTE] > **Note:** The Classic Edge UI is available with Edge for Private Cloud only. 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. ![](https://docs.apigee.com/static/api-platform/images/monetization-reports-classic.png) - View the current list of reports - [Configure a report](https://docs.apigee.com/api-platform/monetization/create-reports#configure) - [Generate and download a report](https://docs.apigee.com/api-platform/monetization/create-reports#download) in CSV format - [Edit a report](https://docs.apigee.com/api-platform/monetization/create-reports#edit) - [Delete a report](https://docs.apigee.com/api-platform/monetization/create-reports#delete) ## 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](https://docs.apigee.com/api-platform/monetization/create-reports#report-types). | 4. Configure the remaining report details based on the report type selected, as described in the following sections: - [Configuring a billing report](https://docs.apigee.com/api-platform/monetization/create-reports#billing-report) - [Configuring a prepaid balance report](https://docs.apigee.com/api-platform/monetization/create-reports#prepaid-balance-report) - [Configuring a revenue report](https://docs.apigee.com/api-platform/monetization/create-reports#revenue-report) 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](https://docs.apigee.com/api-platform/monetization/create-reports#download) 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) > [!NOTE] > **Note:** The Classic Edge UI is available with Edge for Private Cloud only. 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](https://docs.apigee.com/api-platform/monetization/create-reports#report-types). 3. Click **+ Report**. 4. Configure the report details based on the billing type selected, as described in the following sections: - [Configuring a billing report](https://docs.apigee.com/api-platform/monetization/create-reports#billing-report) - [Configuring a prepaid balance report](https://docs.apigee.com/api-platform/monetization/create-reports#prepaid-balance-report) - [Configuring a revenue report](https://docs.apigee.com/api-platform/monetization/create-reports#revenue-report) - [Configuring a variance report](https://docs.apigee.com/api-platform/monetization/create-reports#variance-report) (Deprecated) 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](https://docs.apigee.com/api-platform/monetization/create-reports#download) for more. - Click **Download CSV** to generate and download the report to your local machine as a comma-separated values (CSV) file for viewing. > [!NOTE] > **Note:** The steps in the topics that follow are specific to the Edge UI. The Classic Edge UI steps are similar to those described. ### Configuring a billing report Follow the [steps to configure a report](https://docs.apigee.com/api-platform/monetization/create-reports#steps) 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. > [!NOTE] > **Note:** CHARGE transactions are not included in Detailed reports because of the potentially large number transactions. - **Summary** : Summarizes the total revenues for each API product and developer. > [!NOTE] > **Note:** Custom attributes are not supported in billing summary reports. | | 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](https://docs.apigee.com/api-platform/monetization/create-reports#steps) 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 > [!NOTE] > **Notes:** > > - A revenue report includes data collected up to the end of day before the end date specified via the [`toDate`](https://docs.apigee.com/api-platform/monetization/create-reports#todate) configuration option. Report data collected on the specified end date will be excluded from the report. > - The **Developer Name** in a revenue report is the developer's *legal* name. You can configure the developer legal name using the `MINT_DEVELOPER_LEGAL_NAME` custom attribute, as described in [Configuring monetization attributes](https://docs.apigee.com/api-platform/publish/adding-developers-your-api-product#monetization-attributes). If the developer's legal name is not available, Apigee sets **Developer Name** to the developer's name (first name + last name). Suppose the developer's name is also not specified; Apigee sets the **Developer Name** to `NA`. Follow the [steps to configure a report](https://docs.apigee.com/api-platform/monetization/create-reports#steps) 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. > [!NOTE] > **Note:** If you select a specific currency, the report displays all transactions using that single currency, based on the exchange rate in effect on the date of the transaction. | | Reporting Level | Reporting level. Valid values include: - **Detailed** : Displays each transaction on a separate line. There is no summary. > [!NOTE] > **Note:** CHARGE transactions are not included in Detailed reports because of the potentially large number transactions. - **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. ![](https://docs.apigee.com/static/api-platform/images/Summary-display-options.png) 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](https://docs.apigee.com/api-platform/troubleshoot/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 \ " true \["partner_id","tax_source"] false " ``` 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. > [!WARNING] > **Warning:** 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. ![](https://docs.apigee.com/static/api-platform/images/tx_custom_attributes-ue.png) 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](https://docs.apigee.com/api-platform/monetization/create-reports#critconfigapi). ### Configuring a variance report (Deprecated) > [!NOTE] > Variance reports are deprecated and can only be configured using the Classic Edge UI. Variance reports will be retired in a future release. Follow the [steps to configure a report](https://docs.apigee.com/api-platform/monetization/create-reports#steps) 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. > [!NOTE] > **Note:** 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 | 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. ![](https://docs.apigee.com/static/api-platform/images/Summary-display-options.png) 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.](https://docs.apigee.com/api-platform/monetization/create-reports#ui) 2. Position the cursor over the report you want to download. 3. Under the **Modified** column, click either: 1. The ![CSV file icon](https://docs.apigee.com/static/api-platform/images/monetization-csv-icon.png) icon or the ![zip file icon](https://docs.apigee.com/static/api-platform/images/monetization-zip-icon.png) 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.](https://docs.apigee.com/static/api-platform/images/mon_asynch_download.png) 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. ![](https://docs.apigee.com/static/api-platform/images/Summary-Billing-Report.png) ## Editing a report To edit a report: 1. [Access the Reports page](https://docs.apigee.com/api-platform/monetization/create-reports#ui). 2. Position the cursor over the report you want to edit and click ![](https://docs.apigee.com/static/api-platform/images/edit-icon.png) 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](https://docs.apigee.com/api-platform/monetization/create-reports#ui). 2. Position the cursor over the report that you want to delete. 3. Click ![](https://docs.apigee.com/static/api-platform/images/delete-icon.png) 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](https://docs.apigee.com/api-platform/monetization/create-reports#reportops) 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). > [!NOTE] > **Note:** Report `fromDate` and `toDate` dates and times are in UTC/GMT and can include times. ``` $ 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](https://apidocs.apigee.com/docs/monetization/1/routes/mint/organizations/%7Borg_name%7D/developers/%7Bdeveloper_email%7D/revenue-reports/post). 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](https://docs.apigee.com/api-platform/monetization/create-reports#criteriaops) for further details. > [!NOTE] > **Note:** If required, you can include developer custom attributes in revenue reports, as described in [Including developer custom attributes > in revenue reports using the API](https://docs.apigee.com/api-platform/monetization/create-reports#repdevcustatt). You define custom attributes when adding the developer to your organization, as described in [Managing app > developers](https://docs.apigee.com/api-platform/publish/adding-developers-your-api-product). For example, the following request searches for a revenue report based on various criteria such as report start and end dates and transaction types. > [!NOTE] > **Note:** Report `fromDate` and `toDate` dates and times are in UTC/GMT and can include times. ``` $ 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](https://docs.apigee.com/api-platform/publish/adding-developers-your-api-product). 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](https://docs.apigee.com/api-platform/monetization/create-reports#criteriaops) 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](https://docs.apigee.com/api-platform/monetization/create-reports#criteriaops) 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. > [!NOTE] > **Note:** 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 | | `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"]` Important: For summary reports only, exclude the `org-name@@@` portion of the product ID. For example: `"productIds": ["myproduct", "myproduct2"]`. Otherwise, custom attributes will not be shown in the summary report. | 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. > [!NOTE] > **Note:** `FINAL` status is no longer returned by Apigee monetization. | 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](https://docs.apigee.com/api-platform/monetization/create-reports#customattributes). | N/A | No | | `transactionTypes` | Type of transactions to be included in the report. Valid values include: - `PURCHASE`: Total number of transactions. Applicable to Revenue share plans only. - `CHARGE`: Charge calculated based on [rate card rate plan](https://docs.apigee.com/api-platform/monetization/specify-rate-card-plan-details) and the number of transactions during the usage reporting period which starts from the date the developer [purchased the rate plan](https://docs.apigee.com/api-platform/monetization/subscribe-published-rate-plan-using-api). > [!NOTE] > **Note:** The usage reporting period used to calculate the `CHARGE` value is not the same as the billing period. - `REFUND`: Refunds issued. See [Post refunds](https://docs.apigee.com/api-platform/monetization/post-refunds). - `CREDIT`: Credits issued. See [Issuing credits](https://docs.apigee.com/api-platform/monetization/manage-credit). - `BALANCE`: Balance remaining for prepaid accounts. See [Manage prepaid account balances](https://docs.apigee.com/api-platform/monetization/manage-prepaid-balances). - `SETUPFEES`: Set up fees charged. See [Configuring fees for a rate plan](https://docs.apigee.com/api-platform/monetization/add-fees-rate-plan). - `TERMINATIONFEES`: Early termination fees charged. See [Configuring fees for a rate plan](https://docs.apigee.com/api-platform/monetization/add-fees-rate-plan). - `RECURRINGFEES`: Recurring fees charged. See [Configuring fees for a rate plan using the API](https://docs.apigee.com/api-platform/monetization/add-fees-rate-plan#addfeesapi) and [When are recurring fees charged and bundle plans reset?](https://docs.apigee.com/api-platform/monetization/specify-rate-card-plan-details#reset). - `TRUEUP`: 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 |