Issuing credits

Introduction

Monetization gives you the flexibility to issue developer credit.

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 product bundle. The developer must maintain an adequate balance for purchases.

For a postpaid developer, a credit appears as a separate line in an invoice, reducing the charge in an invoice.

Exploring the Credits page

Access and explore the Credits page using the Edge UI or Classic Edge UI.

Edge UI

To access the Credits page:

  1. Sign in to apigee.com/edge.
  2. Select Publish > Monetization > Credits in the left navigation bar.

The Credits page is displayed.

As highlighted in the figure, the Credits page enables you to:

  • View summary information for all credits, including recipient name, credit amount, date and time the credit is effective, API product bundle and API products to which the credit applies, and any notes added
  • Issue a credit
  • Search the list of credits

Classic Edge UI

To access the Credits page:

  1. Sign in to enterprise.apigee.com.
  2. Select Monetization > Monetization Reports in the top navigation bar.

The Credits page enables you to:

  • View summary information for all credits, including recipient name, credit amount, date and time the credit is effective, API product bundle and API products to which the credit applies, and any notes added
  • Issue a credit
  • Search the list of credits

Issuing a credit

  1. Access the Credits page.
  2. Click + Credit.
  3. Enter the following information:
    Field Description
    Billing Month

    Billing month in which the credit applies. Select a month from the list.

    Developer

    Developer or company name to whom the credit applies. Enter the name in the text box. As you type, a list of the developers/companies that contain the string displays in a drop-down. Click the name of the developer or company from drop-down list.

    Note: After you select a developer or company, remaining fields are displayed. If you select a company or developer that has not accepted a rate plan, you cannot issue a credit.

    Product Bundle

    API product bundle to which the credit applies. Select from the list of available API product bundles.

    Product

    API product in the selected API product bundle to which the credit applies. Select All Products or a single API product from the list.

    Currency

    Currency used for the credit. The currency is configured for the rate plan in the API product bundle that the developer purchased and cannot be changed. If there are multiple currencies defined in a rate plan, you can select from one of the currencies.

    Amount

    Amount of the credit (in the specified currency). Specify a positive or negative value. The value cannot be zero.

    Note

    Optional note to describe the reason for the credit.

  4. Click Save Credit.

Issuing credits using the API

Using the API, issue credit to a developer against an API product bundle as a whole, or against the use of a specific API product in an API product bundle.

To issue a credit using the API, 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} define the identification of the API product bundle and rate plan to which the credit applies, respectively.

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

  • Developer ID (email address) to whom the credit applies.
  • Amount of the credit.
  • Currency used for the credit.
  • Note describing the reason for the credit.

Optionally, you can specify the following additional query parameters:

  • Billing month to which the credit applies. This value defaults to the current month.
  • Billing year to which the credit applies. This value defaults to the current year.
  • API product to which the credit applies. If you don’t specify an API product ID, the credit applies to all API products in the API product bundle.

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

See Query parameters for credits API for a complete list of the query 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 email:password

The following provides an example excerpt of the response:

{
  "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"
}

Query parameters for credits API

The following query parameters are available for use with the credits API:

Name Description Default Required?
billingMonth

Billing month for which the credit applies, such as APRIL.

N/A No
billingYear

Billing year for which the credit applies, such as 2018.

N/A No
currencyId

Currency used for the credit. The currency is configured for the rate plan in the API product bundle that the developer purchased and cannot be changed.

N/A Yes
developerId

Developer or company name to whom the credit applies.

N/A Yes
productId

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

N/A No
transactionAmount

Amount of the credit (in the specified currency). Specify a positive or negative value. The value cannot be zero.

N/A Yes
transactionNote

Note that describes the reason for the credit.

N/A Yes