Send Docs Feedback

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

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

To create an API package, issue a POST request to /organizations/{org_name}/monetization-packages. When you issue the request, you:

  • Identify the products to include in the package.
  • Identify the organization for the package.
  • Specify a name and description for the package.
  • Set a status indicator for the 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.

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 response should look something like this:


{
   "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 product and any custom attributes specified for the product. (Custom attributes are specified when you create an API product — see Specify custom attributes for details.) Custom attributes for a 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

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

About deleting API packages

To ensure the integrity of transaction activity and reporting, you cannot delete or modify API packages after you create them. An API package represents a snapshot of the product(s) they contain. That's also why any subsequent updates to a product are not reflected in an existing package. If you could modify or delete packages, especially when developers are currently signed up for those packages, it would be extremely difficult to reconcile past transactions against those changing packages.

Instead of deleting a package, either let existing rate plans expire so that the packages can no longer be used, or create new packages and tell your developer community to start using those instead. By letting rate plans expire as a way of retiring packages, you also retain transaction records.

If deleting old or unused API packages is important, contact Apigee Support.

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?