You're viewing **Apigee Edge** documentation. [Go to the **Apigee X** documentation](http://cloud.google.com/apigee/docs/api-platform/publish/create-api-products). info Bundle one or more API products into a single monetized container, referred to as an API product bundle, as described in the following sections. > [!IMPORTANT] > **Before you begin** : Ensure that you have created the **API products** that you want to include in the API product bundle. > > > For more information, see the following sections: > > - [What is an API product?](https://docs.apigee.com/api-platform/publish/what-api-product) > - [Manage API products](https://docs.apigee.com/api-platform/publish/create-api-products) > - [Create API products using the API](https://docs.apigee.com/api-platform/publish/using-edge-management-api-publish-apis#configuringapiproducts) ## What is an API product bundle? > [!NOTE] > **Note** : In the Classic Edge UI and the monetization API, product bundles are referred to as **API packages**. An **API product bundle** is a collection of API products that is presented to developers as a group, and typically associated with one or more rate plans for monetization. You can create multiple API product bundles and include one or more API products in each. You can put the same API product or products in different bundles and associate them with different (or the same) rate plans. Developers can register their apps to use an API product bundle only by purchasing one of the rate plans currently in effect. An API product bundle does not become visible to developers until you add and publish (as public) a rate plan for the product bundle (with a start date of the current date or a future date), as described in [Managing rate plans](https://docs.apigee.com/api-platform/monetization/create-rate-plans). After you add and publish a rate plan, developers logging into your developer portal will be able to select the API product bundle and choose the rate plan. Alternatively, you can accept a rate plan for a developer using the management API. For more information, see [Purchase published rate plans using the API](https://docs.apigee.com/api-platform/monetization/subscribe-published-rate-plan-using-api). > [!NOTE] > If an API product bundle doesn't have a published rate plan that is currently in effect, the bundle isn't monetized. When you monetize an API product bundle, you take a frozen-in-time snapshot of the API products, rate plans, and transaction recording policies. To maintain the integrity of the API usage agreements with registered developers, you cannot change the published rate plan once the API product bundle has been published. Modifying a published rate plan would make it difficult to reconcile past transactions against the changed configurations. To learn more about rate plans, see [Manage and publish rate plans](https://docs.apigee.com/api-platform/monetization/intro-rateplans). After you add an API product to an API product bundle, you may need to set up price points for the API product. You need to do this only if all of the following are true: - You set up a revenue sharing rate plan for the API product. - Developers charge third parties for the use of resources in the API product. - There is a minimum or maximum restriction on the amount developers can charge, and you want to notify developers of the restriction. The minimum and maximum prices are displayed in the details for the API product bundle. ## Exploring the Product Bundles page Access the Product Bundles page, as described below. ### Edge To access the API product bundles page using the Edge UI, select **Publish \> Monetization \> Product Bundles** in the left navigation bar. ![](https://docs.apigee.com/static/api-platform/images/api-product-bundle.png) As highlighted in the previous figure, the Product Bundles page enables you to: - View summary information for all product bundles including bundle name and the list of API products that it contains - [Add a product bundle](https://docs.apigee.com/api-platform/monetization/api-product-bundles#add) - [Edit a product bundle](https://docs.apigee.com/api-platform/monetization/api-product-bundles#edit) - Search the list of product bundles on any visible field You can [manage the API products in a product bundle](https://docs.apigee.com/api-platform/monetization/api-product-bundles#addprodtopackapi) or [delete a product bundle](https://docs.apigee.com/api-platform/monetization/api-product-bundles#deletepackage) (if no rate plans are defined) using the API only. ### Classic Edge (Private Cloud) > [!NOTE] > **Note:** The Classic Edge UI is available with Edge for Private Cloud only. To access the API packages page using the Classic Edge UI, select **Publish \> Packages** in the top navigation bar. The API Packages page enables you to: - View summary information for all API packages including the API products it contains and the associated rate plans - Add an API package - Edit an API package - Add and manage rate plans - Toggle the rate plan access setting (public/private) - Filter the list of packages You can [manage the API products in an API package](https://docs.apigee.com/api-platform/monetization/api-product-bundles#addprodtopackapi) or [delete an API package](https://docs.apigee.com/api-platform/monetization/api-product-bundles#deletepackage) (if no rate plans are defined) using the API only. > [!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. ## Adding a product bundle > [!IMPORTANT] > **Best practice:** You can bundle multiple API resources in an API product. However, you must put an API resource in its own API product if you want to charge developers for the use of that API resource separately and be able to report on the use of that resource separately. To add an API product bundle: 1. Click **+ API Product Bundle** on the [Product Bundles page](https://docs.apigee.com/api-platform/monetization/api-product-bundles#ui). 2. Enter a name for the API product bundle. 3. Enter the name of an API product in the Add a Product field. As you type the name of an API product, a list of API products that contain the string displays in a drop-down. Click the name of an API product to add it to the bundle. Repeat to add additional API products. 4. Repeat step 3 to add additional API product names. 5. For each API product that you add, [configure the transaction recording policy](https://docs.apigee.com/api-platform/monetization/create-transaction-recording-policy). 6. Click **Save Product Bundle**. ## Editing a product bundle To edit a product bundle: 1. On the [Product Bundles page](https://docs.apigee.com/api-platform/monetization/api-product-bundles#ui), click within the row of the product bundle that you want to edit. The product bundle panel is displayed. 2. Edit the product bundle fields, as required. See [configure the transaction recording policy](https://docs.apigee.com/api-platform/monetization/create-transaction-recording-policy) for more information. 3. Click **Update Product Bundle**. ## Managing API product bundles using the API The following sections describe how to manage API product bundles using the API. > [!NOTE] > In the Classic Edge UI and the monetization API, product bundles are referred to as **API packages**. ### Creating an API product bundle using the API To create an API product bundle, issue a POST request to `/organizations/{org_name}/monetization-packages`. When you issue the request, you must: - Identify the API products to include in the API product bundle. - Specify a name and description for the API product bundle. - Set a status indicator for the API product bundle. The status indicator can have one of the following values: CREATED, ACTIVE, INACTIVE. Currently, the status indicator value you specify is maintained in the API product bundle, but it is not used for any purpose. Optionally, you can specify the organization. See [API product bundle configuration properties](https://docs.apigee.com/api-platform/monetization/api-product-bundles#pkgops) for a list of options exposed to the API. For example: ``` $ curl -H "Content-Type:application/json" -X POST -d \ '{ "description": "payment messaging package", "displayName": "Payment Messaging Package", "name": "Payment Messaging Package", "organization": { "id": "{org_name}" }, "product": [ { "id": "messaging" }, { "id": "payment" } ], "status": "CREATED" }' \ "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages" \ -u email:password ``` The following provides an example of the response: ``` { "description" : "payment messaging package", "displayName" : "Payment Messaging Package", "id" : "payment_messaging_package", "name" : "Payment Messaging Package", "organization" : { "id" : "{org_name}", "separateInvoiceForFees" : false }, "product" : [ { "customAtt1Name" : "user", "description" : "Messaging", "displayName" : "Messaging", "id" : "messaging", "name" : "messaging", "organization" : { "id" : "{org_name}", "separateInvoiceForFees" : false }, "status" : "CREATED" }, { "customAtt1Name" : "user", "description" : "Payment", "displayName" : "Payment", "id" : "payment", "name" : "payment", "organization" : { "id" : "{org_name}", "separateInvoiceForFees" : false }, "status" : "CREATED" }], "status" : "CREATED" } ``` Notice that the response includes additional information about the API products and any custom attributes specified for those API products. (Custom attributes are specified when you create an API product.) Custom attributes for an API product can be factored into various rate plans. For example, if you set up a rate card plan, where you charge the developer for each transaction, you can set the rate for the plan based on a custom attribute such as the number of bytes transmitted in a transaction. ### Managing the API products in an API product bundle using the API You can add or delete an API product from an API product bundle using the API, as described in the following sections. > [!NOTE] > **Note:** If an API product is in an API product bundle that has a published rate plan and that rate plan has an active subscription, the API product cannot be added to other API packages. This restriction is intended to prevent a company or developer from having more than one active plan on the same API product. #### Adding an API product to an API product bundle To add an API product to an API product bundle, issue a POST request to `organizations/{org_name}/monetization-packages/{package_id}/products/{product_id}`, where `{org_name}` specifies the name of your organization, `{package_id}` specifies the API product bundle name, and `{product_id}` specifies the ID of the API product. > [!NOTE] > **Note:** The ID of the API product is constructed using the API product name converted to all lowercase. Unlike other types of entities, spaces are allowed in API product IDs. For example: ``` $ curl -H "Accept:application/json" -X POST -d \ '{}'\ "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/{package_id}/products/{product_id}" \ -u email:password ``` #### Adding an API product to an API product bundle with API product-specific rate plans To add an API product to an API product bundle that has one or more API product-specific rate plans defined (rate card or revenue share), issue a POST request to `organizations/{org_name}/monetization-packages/{package_id}/products/{product_id}`, where `{org_name}` specifies the name of your organization, `{package_id}` specifies the API product bundle name, and `{product_id}` specifies the ID of the API product. You must pass the rate plan details for the new API product in the request body. Except for the `ratePlanRates` array, the rate plan values must match those specified for all other API products. For more information about the rate plan attributes that can be defined, see [Configuration properties for rate plans](https://docs.apigee.com/api-platform/monetization/create-rate-plans#rateplanops). > [!NOTE] > **Note:** The ID of the API product is constructed using the API product name converted to all lowercase. Unlike other types of entities, spaces are allowed in API product IDs. > > The ID of the rate plan is constructed using the package and rate plan names, as follows: > {package_id}_{rateplanname}. For example: ``` $ curl -H "Content-Type:application/json" -X POST -d \ '{ "ratePlan": [ { "id": "mypackage_rateplan1", "ratePlanDetails": [ { "currency": { "id": "usd" }, "duration": 1, "durationType": "MONTH", "meteringType": "UNIT", "organization" : { "id": "{org_name}", "paymentDueDays": "30", "ratePlanRates": [ { "rate": "1.99", "startUnit": "0", "type": "RATECARD" } ], "ratingParameter": "VOLUME", "type": "RATECARD" } ] } ] }' \ "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/{package_id}/products/{product_id}" \ -u email:password ``` #### Deleting an API product from an API product bundle To delete an API product from an API product bundle, issue a DELETE request to the `organizations/{org_name}/monetization-packages/{package_id}/products/{product_id}`, where `{org_name}` specifies the name of your organization, `{package_id}` specifies the API product bundle name, and `{product_id}` specifies the ID of the API product. > [!NOTE] > **Note:** The ID of the API product is constructed using the API product name converted to all lowercase. Unlike other types of entities, spaces are allowed in API product IDs. For example: ``` $ curl -H "Accept:application/json" -X DELETE \ "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/{package_id}/products/{product_id}" \ -u email:password ``` ### Viewing API product bundles using the API You can retrieve a specific API product bundle or all API product bundles in an organization. You can also retrieve API product bundles that have transactions in a given date range, that is, only packages for which users invoke apps that access APIs in those packages within a specified start and end date. **Viewing a specific API product bundle:** To retrieve a specific API product bundle, issue a GET request to `/organizations/{org_name}/monetization-packages/{package_id}`, where {package_id} is the identification of the API product bundle (the ID is returned in the response when you create the API product bundle). For example: ``` $ curl -H "Accept:application/json" -X GET \ "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/payment_messaging_package" \ -u email:password ``` **Viewing all API product bundles:** To retrieve all API product bundles for an organization, issue a GET request to `/organizations/{org_name}/monetization-packages`. For example: ``` $ curl -H "Accept:application/json" -X GET \ "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages" \ -u email:password ``` You can pass the following query parameters to filter 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. | The response for viewing all API product bundles in an organization should look like this (only part of the response is shown): ``` { "monetizationPackage" : [ { "description" : "payment messaging package", "displayName" : "Payment Messaging Package", "id" : "payment_messaging_package", "name" : "Payment Messaging Package", "organization" : { ... }, "product" : [ { "customAtt1Name" : "user", "description" : "Messaging", "displayName" : "Messaging", "id" : "messaging", "name" : "messaging", "organization" : { ... }, "status" : "CREATED" }, { "customAtt1Name" : "user", "description" : "Payment", "displayName" : "Payment", "id" : "payment", "name" : "payment", "organization" : { ... }, "status" : "CREATED" } ], "status" : "CREATED" }, { "description" : "Communications", "displayName" : "Communications", "id" : "communications", "name" : "Communications", "organization" : { ... }, "product" : [ { "customAtt1Name" : "user", "description" : "Location", "displayName" : "Location", "id" : "location", "name" : "location", "organization" : { ... }, "status" : "CREATED" }, { "customAtt1Name" : "user", "description" : "Messaging", "displayName" : "Messaging", "id" : "messaging", "name" : "messaging", "organization" : { ... }, "status" : "CREATED" } ], "status" : "CREATED" }, { "description" : "Payment", "displayName" : "Payment", "id" : "payment", "name" : "Payment", "organization" : { ... }, "product" : [ { "customAtt1Name" : "user", "description" : "Payment", "displayName" : "Payment", "id" : "payment", "name" : "payment", "organization" : { ... }, "status" : "CREATED" } ], "status" : "CREATED" } ], "totalRecords" : 3 } ``` **Viewing API product bundles with transactions:** To retrieve API product bundles with transactions in a given date range, issue a GET request to `/organizations/{org_name}/packages-with-transactions`. When you issue the request, you need to specify as query parameters a start date and end date for the date range. For example, the following request retrieves API product bundles with transactions during the month of August, 2013. ``` $ curl -H "Accept:application/json" -X GET \ "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/packages-with-transactions?START_DATE=2013-08-01&END_DATE=2013-08-31" \ -u email:password ``` The response should look something like this (only part of the response is shown): ``` { "monetizationPackage" : [ { "description" : "Payment Package", "displayName" : "Payment Package", "id" : "payment_package", "name" : "Payment Package", "organization" : { ... }, "product" : [ { "customAtt1Name" : "user", "customAtt2Name" : "response size", "customAtt3Name" : "content-length", "description" : "payment api product", "displayName" : "payment", "id" : "payment", "name" : "payment", "organization" : { ... }, "status" : "CREATED", "transactionSuccessCriteria" : "status == 'SUCCESS'" } ], "status" : "CREATED" }, { "description" : "messaging package", "displayName" : "Messaging Package", "id" : "messaging_package", "name" : "Messaging Package", "organization" : { ... }, "product" : [ { "customAtt1Name" : "user", "customAtt2Name" : "response size", "customAtt3Name" : "content-length", "description" : "messaging api product", "displayName" : "messaging", "id" : "messaging", "name" : "messaging", "organization" : { ... }, "status" : "CREATED", "transactionSuccessCriteria" : "status == 'SUCCESS'" } ], "status" : "CREATED" }, ... } ] } ``` ### Viewing API product bundles accepted by a developer or company using the API View the API product bundles accepted by a specific developer or company by issuing a GET request to the following APIs, respectively: - `/organizations/{org_name}/developers/{developer_id}/monetization-packages`, where {developer_id} is the ID (email address) of the developer. - `/organizations/{org_name}/companies/{company_id}/monetization-packages`, where {company_id} is the ID of the company. When you issue the request, you can optionally specify the following query parameters: | Query Parameter | Description | Default | |---|---|---| | `current` | Flag that specifies whether to retrieve only active API product bundles (`current=true`) or all packages (`current=false`). All the rate plans in an active package are considered to be available. | `current=false` | | `allAvailable` | Flag that specifies whether to retrieve all available API product bundles (`allAvailable=true`) or only API product bundles available specifically for the developer or company (`allAvailable=false`). All available refers to the API product bundles that are available to the specified developer or company in addition to other developers or companies. API product bundles available specifically to a company or developer only contain rate plans that are available exclusively to that company or developer. | `allAvailable=true` | For example, the following request retrieves all API product bundles accepted by a specific developer: ``` $ curl -H "Accept:application/json" -X GET \ "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/dev1@myorg.com/monetization-packages" \ -u email:password ``` The following request retrieves only active API packages accepted by a specific company: ``` $ curl -H "Accept:application/json" -X GET \ "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/companies/myCompany/monetization-packages?current=true" \ -u email:password ``` ### Deleting an API product bundle using the API You can delete an API product bundle only if it does not have any rate plans defined. > [!NOTE] > **Note:** If you have an API product bundle with draft rate plans defined, you must delete the draft rate plans before you can delete the API product bundle. See [Deleting a rate plan draft > using the API](https://docs.apigee.com/api-platform/monetization/create-rate-plans#deleterpapi). > > To ensure the integrity of transaction activity and reporting, you cannot delete or modify > API product bundles after you have published a rate plan. An API product bundle represents a snapshot of the > API product(s) they contain, and any subsequent updates to an API product are not reflected in > an existing API product bundle. If you could modify or delete API product bundles with rate plans, especially > when developers are currently signed up for those rate plans, it would be extremely difficult > to reconcile past transactions against those changing API product bundles. > > If you have an API product bundle with published rate plans, instead of deleting a package, you can > let existing rate plans expire so that the API product bundles can no longer be used, or create new > API product bundles and direct your developer community to start using those instead. By letting rate > plans expire as a way of retiring API product bundles, you retain their transaction records. To delete an API product bundle that does not have any rate plans defined, issue a DELETE request to `organizations/{org_name}/monetization-packages/{package_id}`, where `{org_name}` specifies the name of your organization and `{package_id}` specifies the API product bundle name. For example: ``` $ curl -H "Accept:application/json" -X DELETE \ "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/{package_id}" \ -u email:password ``` ### API product bundle configuration properties for the API The following API product bundle configuration options are exposed to the API: | Name | Description | Default | Required? | |---|---|---|---| | `description` | A description of the API product bundle. | N/A | Yes | | `displayName` | The name to display for the API product bundle (for example, in a catalog of API packages). | N/A | Yes | | `name` | The name of the API product bundle. | N/A | Yes | | `organization` | The organization that contains the API product bundle. | N/A | No | | `product` | An array of one or more products in the API product bundle. | N/A | No | | `status` | A status indicator for the API product bundle. The status indicator can have one of the following values: CREATED, ACTIVE, INACTIVE. > [!NOTE] > **Note:** Currently, the status indicator value is maintained in the API product bundle, but it is not used. | N/A | Yes |