Send Docs Feedback

Note: Most user interface tasks can be performed in Edge Classic or the New Edge experience. For an overview, getting started topics, and release notes specific to the New Edge experience, see the docs.

Create API packages

Introduction

You've decided which of your API products you want to monetize. Now it's time to put those products into API packages. An API package is a collection of API products that is presented to developers as a bundle, and typically associated with one or more rate plans for monetization.

How developers see your packages and rate plans: When you add a rate plan to a package and publish that rate plan (as long as the rate plan is marked "Public"), developers logging into your developer portal will be able to select the package and choose the rate plan.

You can also accept a rate plan for a developer using the management API. For more information, see Accept published rate plans using the API.

You can create multiple API packages. You decide which API products to include in which API package. You can even put the same API product or products in different packages and associate them with different (or the same) rate plans.

After you add an API product to a package, you may need to set up price points for the product. You need to do this only if all of the following are true:

  • You set up a revenue sharing rate plan for the 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 package.

An API package does not become visible to developers until you publish a rate plan for the package (with a start date of the current date or a future date). 

Developers can register their apps to use an API package only by purchasing one of the rate plans currently in effect.

If an API package doesn't have a published rate plan that is currently in effect, the package isn't monetized.

Toolbox

You can create an API package using the management UI or monetization API. If you use the UI, you create an API package by clicking + Add Product Package in the package catalog.

If you use the API, you create an API package by issuing a POST request to the /organizations/{org_name}/monetization-packages resource.

You can manage the API products in your API package by using the organizations/{org_name}/monetization-packages/{package_id}/products/{product_id} resource.

Creating an API package using the UI

You cannot delete API packages. For more information, see About deleting API packages.

To create an API package:

  1. On the Publish tab, select Packages.

    This opens the package catalog. The package catalog lists the API packages already created in your organization, the API products in those packages, and the associated rate plans.

  2. Click + Add Product Package. This opens the Product Package window.
  3. Enter a package name to identify the API package, and select one or more products to include in the package. The package name must be unique — two API packages cannot have the same package name.

  4. Click Save to save the API package (or Discard to cancel).

    The API package is added to the package catalog.

  5. Click + Add Product Package to create another API package, as needed. Repeat steps 2 through 4 for each API package that you create.

Creating an API package using the API

To create an API package, 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 package.
  • Specify a name and description for the API package.
  • Set a status indicator for the API package. 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 package, but it is not used for any purpose.

Optionally, you can specify the organization.

See API package configuration settings 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 — see Specify custom attributes for details.) 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 package using the API

You can add or delete an API product from an API package using the API, as described in the following sections.

If an API product is in an API package 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 package

To add an API product to an API package, 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 package name, and {product_id} specifies the ID of the API product.

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 package with API product-specific rate plans

To add an API product to an API package 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 package 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 Rate plan configuration settings.

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 contructed 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",
                    "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 package

To delete an API product from an API package, 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 package name, and {product_id} specifies the ID of the API product.

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

You can retrieve a specific API package or all API packages in an organization. You can also retrieve API packages 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 package: To retrieve a specific API package, issue a GET request to /organizations/{org_name}/monetization-packages/{package_id}, where {package_id} is the identification of the API package (the ID is returned in the response when you create the API package). 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 packages: To retrieve all API packages 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 packages. If set to false, the number of API packages returned per page is defined by the size query parameter. Defaults to false.
size Number of API packages 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 packages 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 packages with transactions: To retrieve API packages 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 packages 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 packages accepted by a developer

You can retrieve the API packages accepted by a specific developer. To do that, issue a GET request to /organizations/{org_name}/developers/{developer_id}/monetization-packages, where {developer_id} is the identification of the developer. When you issue the request, you can specify as query parameters:

  • Whether you want to retrieve only active API packages (current=true) or all packages (current=false). All the rate plans in an active package are currently available. The default is current=false.
  • Whether you want to retrieve all available API packages (allAvailable=true) or only API packages available specifically for that developer (allAvailable=false). All available API packages are packages that are available to this developer as well as to other developers. API packages available specifically to a developer only contain rate plans that are available exclusively to that developer. The default is allAvailable=true.

For example, the following request retrieves all API packages 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 developer:

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/dev1@myorg.com/monetization-packages?current=true" \
-u email:password

Deleting an API package

You can delete an API package only if it does not have any rate plans defined. 

If you have an API package with draft rate plans defined, you must delete the draft rate plans before you can delete the API package. See Deleting a rate plan draft using the API.


To ensure the integrity of transaction activity and reporting, you cannot delete or modify API packages after you have published a rate plan. An API package 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 package. If you could modify or delete API packages 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 packages.


If you have an API package with published rate plans, instead of deleting a package, you can let existing rate plans expire so that the API packages can no longer be used, or create new API packages and direct your developer community to start using those instead. By letting rate plans expire as a way of retiring API packages, you retain their transaction records.

To delete an API package 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 package 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 package configuration settings for the API

The following API package configuration options are exposed to the API:

Name Description Default Required?
organization

The organization that contains the API package.

N/A No
name

The name of the API package.

N/A Yes
displayName

The name to display for the API package (for example, in a catalog of API packages).

N/A Yes
description

A description of the API package.

N/A Yes
status

A status indicator for the API package. The status indicator can have one of the following values: CREATED, ACTIVE, INACTIVE.

Currently, the status indicator value is maintained in the API package, but it is not used.

 

N/A Yes
product

An array of one or more products in the API package.

N/A No

Next steps

Learn how to create a transaction recording policy that enables monetization to capture transaction parameters and custom attributes. See Create a transaction recording policy.

Help or comments?