Send Docs Feedback

Create API packages

Introduction

Once you create a package, the only modifications you can make are changing the package name and adding rate plans. You cannot delete the package or add/remove API products.

For more explanation, see About deleting API packages.

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.

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.

You can also set limits on a package or on an API product within a package. For example, you can limit the number of transactions on an API product and set up automatic notification so that the developer (and/or members in your organization) is notified when the number of transactions is approaching the limit. See Set limits for further details.

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.

Creating an API package using the UI

Once you create a package, the only modifications you can make are changing the package name and adding rate plans. You cannot delete the package or add/remove API products.

For more explanation, 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

Once you create a package, the only modifications you can make are changing the package name and adding rate plans. You cannot delete the package or add/remove API products.

For more explanation, 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.

Retrieving 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.

Retrieving 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

Retrieving 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

The response for retrieving 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
}

Retrieving 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"
  },
     ...
  } ]
}

Retrieving 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?