Was this helpful?

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.

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 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 off 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).

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.

After you add API packages, you can perform management operations on them such as update or delete. Management operations on an API package are performed by issuing calls to the /organizations/{org_name}/monetization-packages/{package_id} resource.

Creating an API package using the UI

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:

  • 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 myname:mypass

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 myname:mypass

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 myname:mypass

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 myname:mypass

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 myname:mypass

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 myname:mypass

Updating an API package using the API

To update an API package, issue a PUT request to /organizations/{org_name}/monetization-packages/{package_id}, where {package_id} is the identification of the API package. When you make the update, you need to specify in the request body the updated settings and the ID of the API package. You also need to specify the name and description for the package, the organization name, and the status indicator — even if you don't update those properties. For example, the following request updates the API package whose ID is payment_messaging_package (the updates are highlighted):

$ curl -H "Content-Type: application/json" -X PUT -d \
'{
   "id": "payment_messaging_package",
   "description": "payment messaging package",
   "displayName": "Payment-Messaging",
   "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/payment_messaging_package" \
-u myname:mypass

In response, you should see the following (the updated properties are highlighted and only part of the response is shown):

}  
  "description" : "payment messaging package",
  "displayName" : "Payment-Messaging",
  "id" : "payment_messaging_package",
  "name" : "Payment-Messaging Package",
  "organization" : {
   …
},
  "product" : [ {
    "customAtt1Name" : "user",
    "description" : "Messaging",
    "displayName" : "Messaging",
    "id" : "messaging",
    "name" : "messaging",
    "organization" : {
   …
{
    "customAtt1Name" : "user",
    "description" : "Payment",
    "displayName" : "Payment",
    "id" : "payment",
    "name" : "payment",
    "organization" :
…
},
    "status" : "CREATED"
  ],
  "status" : "CREATED"
}
  "name" : "Payment-Messaging Package",
  "organization" : {
   …
},
  "product" : [ {
    "customAtt1Name" : "user",
    "description" : "Messaging",
    "displayName" : "Messaging",
    "id" : "messaging",
    "name" : "messaging",
    "organization" : {
   …
{
    "customAtt1Name" : "user",
    "description" : "Payment",
    "displayName" : "Payment",
    "id" : "payment",
    "name" : "payment",
    "organization" :
…
},
    "status" : "CREATED"
  ],
  "status" : "CREATED"
}

API package configuration settings

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

Get help

For help, see Apigee Customer 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?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)