Was this helpful?

Introduction

Monetization gives you the flexibility to issue developer credit. For a postpaid developer, a credit appears as a separate line in an invoice, reducing the charge in an invoice.

For a prepaid developer, a credit appears as a reduction in usage — this increases the developer’s prepaid balance going forward. Much like using a debit card, funds are withdrawn from a developer’s prepaid balance when the developer purchases an API package. The developer must maintain an adequate balance for purchases.

Once you issue a credit to a developer, you cannot change it directly. However, you can effectively change or remove the credit by creating a credit with a negative amount for the same developer.

You can also set a credit limit for postpaid developers. This means that you can issue credit to applicable postpaid developers up to the credit limit.

Toolbox

You can issue credit using the management UI or monetization API.

If you use the UI, you issue credit on the Credits page.

If you use the API, you can apply credit against a package as a whole, or against the use of a specific product within a package. You apply a credit against a package by issuing a POST request to the /organizations/{org_name}/monetization-packages/{package_id}/rate-plans/{rate-plan_id}/real-currency-credit-transactions resource. Optionally, you can identify as a query parameter an API product to which the credit applies.

Using the API, you can set a credit limit for a postpaid developer by issuing a POST request to /organizations/{org_name}/developers/{developer_id}/developer-credit-limit.

Issuing credit using the UI

  1. On the Monetization tab, select Credits.

    This opens the Credits page.

  2. On the Credits page, click +Credit.

    This opens a New Credit window.

  3. Enter the following information:

     

    Field Description
    Month

    The month in which the credit applies. Select either Current Month or Previous month.

    Developer

    The developer to whom the credit applies. Select a developer from the drop-down menu.

    Package

    The API package for which the credit applies. Select an API package from the drop-down menu.

    Product

    The API product in the selected API package for which the credit applies. Select an API package from the drop-down menu. You can select All Products in the package or a specific product.

    Currency

    The currency used for the credit. This is the currency that was set up for the plan in the package that the developer purchased (it cannot be changed). If there are multiple currencies in a plan, you can select from one of the currencies.

    Notes

    A text note to describe the reason for the credit.

  4. Click Save to save the credit (or Cancel to cancel).

     

  5. The credit is added to the list of credits on the Credits page.

Issuing credit using the API

You can issue credit to a developer. You can apply credit against a package as a whole, or against the use of a specific product within a package.

To issue a credit, issue a POST request to /organizations/{org_name}/monetization-packages/{package_id}/rate-plans/{rate-plan_id}/real-currency-credit-transactions, where {package_id} and {rate-plan_id} are respectively the identification of the API package and rate plan to which the credit applies.

When you issue the request, you need to specify as query parameters:

  • The identification of the developer to whom the credit applies.
  • The amount of the credit.
  • The currency used for the credit.
  • A note describing the reason for the credit.
  • The billing month to which the credit applies.
  • The billing year to which the credit applies.

Optionally, you can identify as a query parameter an API product to which the credit applies. If you don’t specify a product ID, the credit applies to all products in the API package.

For example, the following request issues a credit of $100 for the billing month of April 2013 to a developer identified as dev1@myorg.com. The credit applies to the payment package and payment_standard_plan rate plan:

See Credit configuration settings for a complete list of the URL parameters that you can specify in a credit request.

$ curl -H "Content-Type:application/json" -X POST \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/payment/rate-plans/payment_standard_plan/real-currency-credit-transactions?currencyId=usd&developerId=dev1@myorg.com&transactionAmount=100&transactionNote=Credit+for+failed+transactions&billingMonth=APRIL&billingYear=2013" \
-u myname:mypass

The response should look something like this (only part of the response is shown):

{
  "currency" : "USD",
  "developer" : {
    "address" : [ {
      "address1" : "Dev One Address",
     ...
    } ],
    "approxTaxRate" : 0.0000,
    "billingType" : "PREPAID",
    "broker" : false,
    "developerRole" : [ ],
    "email" : "dev1@myorg.com",
    "hasSelfBilling" : false,
    "id" : "K4jW2QLjZ1h8GFA8",
    "legalName" : "DEV ONE",
    "name" : "Dev One",
    "organization" : {
     ...
    },
    "registrationId" : "TestRegId",
    "status" : "ACTIVE",
    "type" : "TRUSTED"
  },
  "endTime" : "2013-09-04 15:54:36",
  "environment" : "PROD",
  "euroExchangeRate" : 0.8107,
  "gbpExchangeRate" : 0.6860,
  "id" : "904c3f73-ab8d-4e5d-a48c-225fd49a3bde",
  "isVirtualCurrency" : false,
  "notes" : "Credit for failed transactions",
  "pkgId" : "myorg@@@payment",
  "pkgRatePlanProductName" : "Payment",
  "providerTxId" : "904c3f73-ab8d-4e5d-a48c-225fd49a3bde",
  "rate" : 100,
  "ratePlan" : {
    ...
      },
      "status" : "ACTIVE",
      "virtualCurrency" : false
    },
    "description" : "Standard Plan",
    "displayName" : "Standard Plan",
    …
    "monetizationPackage" : {
      "description" : "Payment",
      ...
        } ],
       ...
      },
      "product" : [ {
        "customAtt1Name" : "user",
        "description" : "Payment",
        "displayName" : "Payment",
        "id" : "payment",
        "name" : "payment",
        "organization" : {
          ...
        },
        "status" : "CREATED",
        "transactionSuccessCriteria" : "Status=='200 OK'"
      } ],
      "status" : "CREATED"
    },
    "name" : "Standard Plan",
    "organization" : {
     ...
    },
    ...
      },
      ...
      },
      ...
  },
  "revenueShareAmount" : 0,
  "startTime" : "2013-09-04 15:54:36",
  "status" : "SUCCESS",
  "taxModel" : "UNDISCLOSED",
  "txProviderStatus" : "SUCCESS",
  "type" : "CREDIT",
  "usdExchangeRate" : 1.0675,
  "utcEndTime" : "2013-09-04 15:54:36",
  "utcStartTime" : "2013-09-04 15:54:36"
}

Setting a credit limit using the API

When you add a supported currency for an organization, you can set a credit limit (see Adding supported currencies). The credit limit applies to all postpaid developers in the organization. This means that you can issue credit to the postpaid developers in the organization up to that limit. However, you can also set a credit limit for an individual postpaid developer. If you do that, the limit overrides any supported currency limit, but only for that developer.

To set a credit limit for an individual developer, issue a POST request to /organizations/{org_name}/developers/{developer_id}/developer-credit-limit, where {developer_id} is the identification of the developer. When you issue the request, you need to specify as query parameters the amount of the credit and the currency used for the credit. For example, the following request sets a credit limit of $1000 for a developer:

$ curl -H "Content-Type:application/json" -X POST \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/dev7@myorg/developer-credit-limit?amount=1000&supportedCurrencyId=usd" \
-u myname:mypass

Retrieving a credit limit using the API

To retrieve a credit limit for a postpaid developer issue a GET request to /organizations/{org_name}/developers/{developer_id}/developer-credit-limit, where {developer_id} is the identification of the developer. For example:

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/dev7@myorg/developer-credit-limit" \
-u myname:mypass

The response should look something like this (only part of the response is shown):

{
  "developerBalance" : [ {
    "amount" : 1000.0000,
    "id" : "ddd98cd5-06bc-481b-ae42-76a7345933a9",
    "supportedCurrency" : {
      "description" : "United States Dollar",
      "displayName" : "United States Dollar",
      "id" : "usd",
      "name" : "USD",
      "organization" : {
        ...
      },
      "status" : "ACTIVE",
      "virtualCurrency" : false
    },
    "usage" : 76.6052
  } ],
  "totalRecords" : 1
}

Credit configuration settings

The following query parameters are available for credits:

Name Description Default Required?
developerId

The developer to whom the credit applies.

N/A Yes
productId

The API product for which the credit applies. If you do not specify a product ID, the credit applies to all products in the API package.

N/A No
transactionAmount

The amount of the credit (in the applicable currency).

N/A Yes
currencyId

The currency used for the credit. This is the currency that was set up for the plan in the package that the developer purchased.

N/A Yes
transasctionNote

A text note that describes the reason for the credit.

N/A Yes
billingMonth

The billing month for which the credit applies, such as APRIL.

N/A Yes
billingYear

The billing year for which the credit applies, such as 2013.

N/A Yes

Get help

For help, see Apigee Customer Support.

Next steps

Using monetization, you can "top up" (that is, raise the amount of) a developer's prepaid balance. You can also retrieve a developer's prepaid balance. Learn how in Manage prepaid balances.

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