Managing rate plans for API products

You're viewing Apigee X documentation.
View Apigee Edge documentation.

Using rate plans, API product owners can monetize their API products by configuring the following:

  • Billing account model (postpaid only)
  • Currency used for billing
  • Frequency at which customers are billed (monthly only)
  • Consumption-based charges for using an API product
  • Time interval during which the rate plan is in effect for an API product (rate plan activation and expiration times)

Manage rate plans for your API products as described in the following sections.

Viewing rate plans

View rate plans in your organization as described in the following sections.

Apigee UI

View rate plans using the UI as described in the following sections:

Viewing rate plans defined for your organization

View rate plans defined for your organization on the Rate plans page.

To access the Rate plans page:

  1. Sign in to the Apigee UI.
  2. Select Publish> Monetization> Rate Plans in the side navigation bar.

The Rate Plans page opens and lists the current rate plans.

List of rate plans showing rate plan name, API product, and activation and expiration times for each, plus the drop-down that can be used to manage the rate plan

As highlighted in the previous figure, the Rate Plans page enables you to:

Viewing rate plans associated with an API product

When managing an API product, you can view and manage the rate plans associated with an API product, as shown in the following figure.

API Products page with the Rate plans section highlighted

Apigee API

The following sections describe how to view rate plans for an organization using the API:

Listing the rate plans for an API product using the API

To list the rate plans for the organization, issue a GET request to the following API: https://apigee.googleapis.com/v1/organizations/$ORG/apiproducts/$APIPRODUCT/rateplans

For example using curl:

curl "https://apigee.googleapis.com/v1/organizations/$ORG/apiproducts/$APIPRODUCT/rateplans?expand=true" \
  -X GET \
  -H "Authorization: Bearer $TOKEN"

Where $TOKEN is set to your OAuth 2.0 access token, as described in Obtaining an OAuth 2.0 access token. For information about the curl options used in this example, see Using curl. For a description of the environment variables used, see Setting environment variables for Apigee API requests.

The following provides an example of the response output, including the three rate plans, myrateplan1, myrateplan2, and myrateplan3 associated with HelloworldProduct API product:

{
  "ratePlans": [
    {
      "name": "3cdcff51-3a23-4726-906d-e222c7e9ff3a",
      "apiproduct": "HelloworldProduct",
      "displayName": "myrateplan2",
      "billingPeriod": "MONTHLY",
      "currencyCode": "USD",
      "state": "DRAFT",
      "startTime": "1615179600000",
      "endTime": "1615299719090"
    },
    {
      "name": "69f8bb42-a8e4-4a2c-b932-d82b51d37b72",
      "apiproduct": "HelloworldProduct",
      "displayName": "myrateplan1",
      "billingPeriod": "MONTHLY",
      "currencyCode": "USD","state": "PUBLISHED",
      "startTime": "1615129396651",
      "endTime": "1615265999999"
    },
    {
      "name": "cc6252c0-c5d0-4aaf-85f2-203ec8fa5707",
      "apiproduct": "HelloworldProduct",
      "displayName": "myrateplan3",
      "billingPeriod": "MONTHLY",
      "currencyCode": "USD",
      "state": "PUBLISHED",
      "startTime": "1615302703609"
    }
  ]
}

For more information about the API and its response payload, see the List rate plans API

Viewing details for a rate plan using the API

To view details for a rate plan, issue a GET request to the following API: https://apigee.googleapis.com/v1/organizations/$ORG/apiproducts/$APIPRODUCT/rateplans/$RATEPLAN

To determine the name of the rate plan to pass in the resource path, see Listing the rate plans in an organization.

For example using curl:

curl "https://apigee.googleapis.com/v1/organizations/$ORG/apiproducts/$APIPRODUCT/rateplans/$RATEPLAN" \
  -X GET \
  -H "Authorization: Bearer $TOKEN"

Where $TOKEN is set to your OAuth 2.0 access token, as described in Obtaining an OAuth 2.0 access token. For information about the curl options used in this example, see Using curl. For a description of the environment variables used, see Setting environment variables for Apigee API requests.

The following provides an example of the response output for the rate plan with the name 69f8bb42-a8e4-4a2c-b932-d82b51d37b72 and display name myrateplan1:

{
  "ratePlans": [
    {
      "name": "69f8bb42-a8e4-4a2c-b932-d82b51d37b72",
      "apiproduct": "HelloworldProduct",
      "displayName": "myrateplan1",
      "billingPeriod": "MONTHLY",
      "currencyCode": "USD","consumptionPricingType": "FIXED_PER_UNIT",
      "consumptionPricingRates": [
        {
          "fee": {
            "currencyCode": "USD",
            "units": "3"
          }
        }
      ],
      "state": "PUBLISHED",
      "startTime": "1615129396651",
      "endTime": "1615265999999"
    }
  ]
}

For more information about the API and its response payload, see the Get rate plan API

Creating rate plans

Create rate plans as described in the following sections.

Apigee UI

To create a rate plan using the UI:

  1. Perform one of the following tasks:
    • Select Publish> Monetization> Rate Plans in the side navigation bar and click Create rate plan.
    • Edit an API product and click Add button in the Rate plans section.
  2. Enter Rate plan details, as follows:
    Field Description
    Rate plan name Enter the name of the rate plan.
    API product Select an API product to which you want to associate the rate plan from the drop-down.
  3. Click Next.
  4. Enter Billing details, as follows:
    Field Description Default
    Billing currency Select the currency to use for billing from the drop-down. USD
    Billing period Select the frequency at which the customer will be billed from the drop-down. Monthly
    Payment funding model Select the payment model used for funding accounts. Postpaid is the only valid option in this release. With Postpaid funding models, your customers receive an invoice for payment at the end of each billing period. Postpaid
  5. Click Next.
  6. Enter Pricing details as follows.
    Field Description Default
    Consumption based fee Enable consumption-based pricing:
    1. Select Charge consumption-based fee.
    2. Select Fixed fee per unit (flat fee per unit consumed).
    3. Set the Fixed fee per unit charged every billng period based on consumption.

    If enabled, you can preview the effects that example API consumption values have on the itemized and total charges, as described in Previewing your rate plan.

    To disable the fee, deselect Charge consumption-based pricing model.

    Disabled
  7. Click one of the following:

Apigee API

To create a rate plan, issue a POST request to the following API: https://apigee.googleapis.com/v1/organizations/$ORG/apiproducts/$APIPRODUCT/rateplans

Configure the rate plan by passing the required fields in the request body, as described in Resource: RatePlans.

The following table summarizes the required fields when creating a draft and published rate plan.

Required fields for draft rate plan Required fields for published rate plan
  • apiproduct
  • displayName
  • state
  • apiproduct
  • billingPeriod
  • currencyCode
  • displayName
  • paymentFundingModel
  • startTime
  • state

For example, the following API call creates a draft rate plan named rateplan1 associated with the HelloworldProduct API product:

curl "https://apigee.googleapis.com/v1/organizations/$ORG/apiproducts/HelloworldProduct/rateplans" \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-type: application/json" \
  -d '{
    "apiproduct":"HelloworldProduct",
    "billingPeriod":"MONTHLY",
    "consumptionPricingType":"FIXED_PER_UNIT",
    "consumptionPricingRates":[{
       "fee":{
          "units":"3",
          "nanos":0
        }
    }],
    "currencyCode":"USD",
    "displayName":"rateplan1","state":"DRAFT"
    }'

Where $TOKEN is set to your OAuth 2.0 access token, as described in Obtaining an OAuth 2.0 access token. For information about the curl options used in this example, see Using curl. For a description of the environment variables used, see Setting environment variables for Apigee API requests.

The following provides an example of the response output:

{
   "name": "69f8bb42-a8e4-4a2c-b932-d82b51d37b72",
   "apiproduct": "HelloworldProduct",
   "displayName": "rateplan1",
   "billingPeriod": "MONTHLY",
   "paymentFundingModel" : "POSTPAID",
   "currencyCode": "USD","consumptionPricingType": "FIXED_PER_UNIT",
   "consumptionPricingRates": [
   {
      "fee": {
         "currencyCode": "USD",
         "units": "3"
       }
   }
   ],
   "state": "DRAFT"
}

For more information, see the Create rate plan API

Previewing your rate plan in the UI

Based on your pricing configuration, you can preview the itemized charges and billed totals in the Rate plan preview section of the Rate plan page, as shown in the following figure.

Enter example values, see results in the rate plan preview

Update the API unit consumption field in the Example consumer data section. The itemized charges and totals are updated based on your input.

Setting the activation and expiration times for rate plans

Set activation and expiration times for a rate plan to indicate when a published rate plan is active and that the associated API product is available for developers to use in their apps.

Consider the following when setting activation and expiration times:

  • Only one rate plan can be active for an API product at any given time.
  • You can publish multiple rate plans for the same API product with non-overlapping activation and expiration times.
  • You must set the activation time for a rate plan before it can be published.
    When publishing a rate plan using the UI, you will be prompted to set the activation time if it is not set.
  • The activation time must occur before the expiration time (if set), and the expiration time must occur after the activation time.
  • The expiration time is not required. If not specified, the expiration defaults to Never (the rate plan never expires).
  • When setting the activation and expiration times using the UI, you can specify only the date and not the time of day (hh:mm:ss:mmm). The time of day for the activation and expiration values defaults to 12:00:00:000 AM and 11:59:59:999 PM, respectively.

Set the activation and expiration times for rate plans as described in the following sections.

Apigee UI

To set the activation time for a rate plan using the UI:

  1. Access the Rate Plans page.
  2. Click > Set activation for the rate plan for which you want to set the activation time.
  3. Select one of the following options:
    • Undetermined to unset the rate plan activation time (available for draft rate plans only).
    • Immediately to set the rate plan as active immediately.
    • On a future date to select the date on which the rate plan will be active.
  4. Click Set activation.
  5. Publish the rate plan if it is not yet published to make it available to developers to use in their apps.

To set the expiration time for a rate plan using the UI:

  1. Access the Rate Plans page.
  2. Click > Set expiration for the rate plan for which you want to set the expiration time.
  3. Select one of the following options:
    • Never to never expire the rate plan.
    • Immediately to set the rate plan as active immediately.
    • On a future date to select the date on which the rate plan will be active.
  4. Click Set expiration.

Apigee API

To set the activation or expiration times for a rate plan using the API:

  1. View the details for the rate plan you want to update.
  2. Use the response to create the request body and update the following fields:
    • startTime to set the activation time
    • endTime to set the expiration time
  3. To update the rate plan with the new configuration, issue a PUT request to the following API, passing the modified request body in your request: https://apigee.googleapis.com/v1/organizations/$ORG/apiproducts/$APIPRODUCT/rateplans/$RATEPLAN

For example, the following sets the activation time to April 1, 2021 (1617302588000 epoch time):

curl "https://apigee.googleapis.com/v1/organizations/$ORG/apiproducts/$APIPRODUCT/rateplans/69f8bb42-a8e4-4a2c-b932-d82b51d37b72" \
  -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-type: application/json" \
  -d '{
    "apiproduct": "HelloworldProduct",
    "displayName": "myrateplan1",
    "currencyCode":"USD",
    "billingPeriod":"MONTHLY",
    "paymentFundingModel" : "POSTPAID","consumptionPricingType":"FIXED_PER_UNIT",
    "consumptionPricingRates":[{
       "fee":{
          "units":"3",
          "nanos":0
        }
    }],
    "state":"PUBLISHED",
    "startTime": 1617302588000
    }'

Where $TOKEN is set to your OAuth 2.0 access token, as described in Obtaining an OAuth 2.0 access token. For information about the curl options used in this example, see Using curl. For a description of the environment variables used, see Setting environment variables for Apigee API requests.

For more information about the fields you can specify in the request body, see Resource: RatePlans.

The following provides an example of the response output:

{
  "name": "69f8bb42-a8e4-4a2c-b932-d82b51d37b72",
  "apiproduct": "HelloworldProduct",
  "displayName": "myrateplan1",
  "billingPeriod": "MONTHLY",
  "paymentFundingModel" : "POSTPAID",
  "currencyCode": "USD","consumptionPricingType": "FIXED_PER_UNIT",
  "consumptionPricingRates": [
    {
      "fee": {
        "units": "3"
      }
    }
  ],
  "state": "PUBLISHED",
  "startTime": "1617302588000"
}

For more information, see the Update rate plan API

Publishing rate plans

Publish rate plans as described in the following sections.

Apigee UI

To publish a rate plan using the UI, use one of the following methods:

  • When creating or updating a rate plan, you can click Save and Publish to save and publish the rate plan. You will be prompted to set the activation date.
  • Access the Rate Plans page and click > Publish for the draft rate plan you want to publish.

    This option appears only if you have set an activation date for the draft rate plan.

Apigee API

To publish a rate plan using the API:

  1. View the details for the rate plan you want to publish.
  2. Use the response to create the request body and update the following fields:
    • Set state to PUBLISHED.
    • Set startTime to the activation time in milliseconds since epoch.
    • Optionally, set endTime to the expiration time in milliseconds since epoch or to Never. If omitted, the expiration time defaults to Never.
    • Set any other fields that you wish to maintain.
  3. To publish the rate plan, issue a PUT request to the following API, passing the modified request body in your request: https://apigee.googleapis.com/v1/organizations/$ORG/apiproducts/$APIPRODUCT/rateplans/$RATEPLAN

For example, the following changes the status of the rateplan1 rate plan to PUBLISHED and sets the activation time to April 1, 2021, specified as milliseconds since epoch:

curl "https://apigee.googleapis.com/v1/organizations/$ORG/apiproducts/$APIPRODUCT/rateplans/69f8bb42-a8e4-4a2c-b932-d82b51d37b72" \
  -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-type: application/json" \
  -d '{
    "apiproduct": "HelloworldProduct",
    "displayName": "myrateplan1",
    "currencyCode":"USD",
    "billingPeriod":"MONTHLY",
    "paymentFundingModel" : "POSTPAID","consumptionPricingType":"FIXED_PER_UNIT",
    "consumptionPricingRates":[{
       "fee":{
          "units":"3",
          "nanos":0
        }
    }],
    "state":"PUBLISHED",
    "startTime": 1617302588000
    }'

For more information about the fields you can specify in the request body, see Resource: RatePlans.

Where $TOKEN is set to your OAuth 2.0 access token, as described in Obtaining an OAuth 2.0 access token. For information about the curl options used in this example, see Using curl. For a description of the environment variables used, see Setting environment variables for Apigee API requests.

The following provides an example of the response output:

{
  "name": "69f8bb42-a8e4-4a2c-b932-d82b51d37b72",
  "apiproduct": "HelloworldProduct",
  "displayName": "myrateplan1",
  "billingPeriod": "MONTHLY",
  "paymentFundingModel" : "POSTPAID",
  "currencyCode": "USD","consumptionPricingType": "FIXED_PER_UNIT",
  "consumptionPricingRates": [
    {
      "fee": {
        "units": "3"
      }
    }
  ],
  "state": "PUBLISHED",
  "startTime": "1617302588000"
}

For more information, see the Update rate plan API

Moving published rate plans to draft status

Move published rate plans to draft status as described in the following sections.

Apigee UI

To move a published rate plan to draft status using the UI:

  1. Access the Rate Plans page.
  2. Select > Move to draft.

The rate plan is updated and the Status field is changed to Draft.

Apigee API

To move a published rate plan to draft status using the API:

  1. View the details for the published rate plan you want to move to draft status.
  2. Use the response to create the request body and update the following fields:
    • Set state to DRAFT.
    • Set any other fields that you wish to maintain.
  3. To move the published rate plan to draft status, issue a PUT request to the following API, passing the modified request body in your request: https://apigee.googleapis.com/v1/organizations/$ORG/apiproducts/$APIPRODUCT/rateplans/$RATEPLAN

For example, the following changes the status of the rateplan1 rate plan to DRAFT:

curl "https://apigee.googleapis.com/v1/organizations/$ORG/apiproducts/$APIPRODUCT/rateplans/69f8bb42-a8e4-4a2c-b932-d82b51d37b72" \
  -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-type: application/json" \
  -d '{
    "apiproduct": "HelloworldProduct",
    "displayName": "myrateplan1",
    "currencyCode":"USD",
    "billingPeriod":"MONTHLY",
    "paymentFundingModel" : "POSTPAID","consumptionPricingType":"FIXED_PER_UNIT",
    "consumptionPricingRates":[{
       "fee":{
          "units":"3",
          "nanos":0
        }
    }],
    "state":"DRAFT",
    "startTime": 1617302588000
    }'

For more information about the fields you can specify in the request body, see Resource: RatePlans.

Where $TOKEN is set to your OAuth 2.0 access token, as described in Obtaining an OAuth 2.0 access token. For information about the curl options used in this example, see Using curl. For a description of the environment variables used, see Setting environment variables for Apigee API requests.

The following provides an example of the response output:

{
  "name": "69f8bb42-a8e4-4a2c-b932-d82b51d37b72",
  "apiproduct": "HelloworldProduct",
  "displayName": "myrateplan1",
  "billingPeriod": "MONTHLY",
  "paymentFundingModel" : "POSTPAID",
  "currencyCode": "USD","consumptionPricingType": "FIXED_PER_UNIT",
  "consumptionPricingRates": [
    {
      "fee": {
        "units": "3"
      }
    }
  ],
  "state": "DRAFT",
  "startTime": "1617302588000"
}

For more information, see the Update rate plan API

Updating rate plans

Update rate plans as described in the following sections. See also:

Update a rate plan as described in the following sections.

Apigee UI

To update a rate plan using the UI:

  1. Access the Rate Plans page.
  2. Click the name of the rate plan that you want to update in the list.
  3. Update the rate plan, as required.
  4. Click one of the following:
    • Save and publish to save and publish the rate plan. You will be prompted for an activation date. For more information, see Setting the activation date for a rate plan.
    • Save to save a draft of the rate plan.
    • Cancel to cancel your updates.

Apigee API

To update a rate plan using the API:

  1. View the details for the rate plan you want to update.
  2. Use the response to create the request body and update any other configuration settings, as required.
  3. To update a rate plan, issue a PUT request to the following API, passing the modified request body in your request: https://apigee.googleapis.com/v1/organizations/$ORG/apiproducts/$APIPRODUCT/rateplans/$RATEPLAN

For example, the following changes the consumption-based fee to 5; all other configuration settings are included to ensure that they are maintained:

curl "https://apigee.googleapis.com/v1/organizations/$ORG/apiproducts/$APIPRODUCT/rateplans/69f8bb42-a8e4-4a2c-b932-d82b51d37b72" \
  -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-type: application/json" \
  -d '{
    "apiproduct": "HelloworldProduct",
    "displayName": "myrateplan1",
    "currencyCode":"USD",
    "billingPeriod":"MONTHLY",
    "paymentFundingModel" : "POSTPAID","consumptionPricingType":"FIXED_PER_UNIT",
    "consumptionPricingRates":[{
       "fee":{
          "units":"5",
          "nanos":0
        }
    }],
    "state":"PUBLISHED",
    "startTime": 1617302588000
    }'

For more information about the fields you can specify in the request body, see Resource: RatePlans.

Where $TOKEN is set to your OAuth 2.0 access token, as described in Obtaining an OAuth 2.0 access token. For information about the curl options used in this example, see Using curl. For a description of the environment variables used, see Setting environment variables for Apigee API requests.

The following provides an example of the response output:

{
  "name": "69f8bb42-a8e4-4a2c-b932-d82b51d37b72",
  "apiproduct": "HelloworldProduct",
  "displayName": "myrateplan1",
  "billingPeriod": "MONTHLY",
  "paymentFundingModel" : "POSTPAID",
  "currencyCode": "USD","consumptionPricingType": "FIXED_PER_UNIT",
  "consumptionPricingRates": [
    {
      "fee": {
        "units": "5"
      }
    }
  ],
  "state": "PUBLISHED",
  "startTime": "1617302588000"
}

For more information, see the Update rate plan API

Cloning rate plans

Clone rate plans as described in the following sections.

Apigee UI

To clone a rate plan using the UI:

  1. Access the Rate Plans page.
  2. Select > Clone.
  3. Update the Rate plan name and API product fields, as required.
  4. Click Clone.

The rate plan is added to the list of rate plans.

Apigee API

To clone a rate plan using the API:

  1. View the details for the rate plan you want to clone.
  2. Use the response to create the request body and update the following fields:
    • Remove the name field.
    • Update any other configuration settings, as required.
  3. Create a rate plan by passing the modified request body in your request.

Deleting rate plans

Deleting a rate plan is permanent. The rate plan will be deleted immediately and cannot be restored.

Delete rate plans as described in the following sections.

Apigee UI

To delete a rate plan using the UI:

  1. Access the Rate Plans page.
  2. Select > Delete for the rate plan that you want to delete.
  3. Click Delete when prompted to confirm the deletion.

The rate plan is deleted and removed from the list.

Apigee API

To delete a rate plan, issue a DELETE request to the following API: https://apigee.googleapis.com/v1/organizations/$ORG/apiproducts/$APIPRODUCT/rateplans/$RATEPLAN.

To determine the name of the rate plan to pass in the resource path, see Listing the rate plans in an organization.

For example, the following deletes the rate plan with name cc6252c0-c5d0-4aaf-85f2-203ec8fa5707 and display name myrateplan3:

curl "https://apigee.googleapis.com/v1/organizations/$ORG/apiproducts/$APIPRODUCT/rateplans/cc6252c0-c5d0-4aaf-85f2-203ec8fa5707" \
  -X DELETE \
  -H "Authorization: Bearer $TOKEN

Where $TOKEN is set to your OAuth 2.0 access token, as described in Obtaining an OAuth 2.0 access token. For information about the curl options used in this example, see Using curl. For a description of the environment variables used, see Setting environment variables for Apigee API requests.

The following provides an example of the response output:

{
   "name": "cc6252c0-c5d0-4aaf-85f2-203ec8fa5707",
   "apiproduct": "HelloworldProduct",
   "displayName": "myrateplan3",
   "paymentFundingModel" : "POSTPAID",
   "billingPeriod": "MONTHLY",
   "currencyCode": "USD",
   "state": "PUBLISHED",
   "startTime": "1615302703609"
}

For more information, see the Delete rate plans API.