Issuing credits

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

Introduction

Monetization gives you the flexibility to issue developer credit.

For a prepaid developer, a credit appears as a reduction in usage — this increases or decreases 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. See How do I calculate the remaining prepaid account balance?

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, as described below.

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