Introduction

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.

Toolbox

You use the monetization API to top up a developer's prepaid balance by issuing a POST request to the /organizations/{org_name}/developers/{developer_id}/developer-balances resource. You retrieve a developer's prepaid balance by issuing a GET request to the /organizations/{org_name}/developers/{developer_id}/developer-balances resource.

Topping up a prepaid balance using the API

To top up a developer’s prepaid balance, issue a POST request to /organizations/{org_name}/developers/{developer_id}/developer-balances, where {developer_id} is the identification of the developer. When you issue the request, you need to specify in the request body the amount to add to the balance and the currency used for the balance. For example, the following request adds $1000 to a developer's prepaid balance:

$ curl -H "Content-Type:application/json" -X POST -d \
'{
  "amount": 1000,
  "supportedCurrency": {
      "id": "usd" 
  } 
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/dev2@example.com/developer-balances" \
-u myname:mypass

Retrieving balances using the API

To retrieve a developer's balances issue a GET request to /organizations/{org_name}/developers/{developer_id}/developer-balances, where {developer_id} is the identification of the developer. If the developer is a prepaid developer, the request retrieves the developer's current prepaid balance. If the developer is a postpaid developer, the request retrieves the developer's current credit limit.

For example:

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

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

  "developerBalance" : [ {
    "amount" : 1000.0000,
    "id" : "00dacce3-e7d6-4ab4-bcf4-1134efe7ba95",
    "supportedCurrency" : {
      "description" : "POINTS",
      "displayName" : "POINTS",
      "id" : "points",
      "name" : "POINTS",
      "organization" : {
        ...
      "status" : "ACTIVE",
      "virtualCurrency" : true
    },
    "usage" : 818.0450
  }, {
    "amount" : 13002.0000,
    "id" : "823397ac-ce2d-437e-9889-d9f745ebe128",
    "supportedCurrency" : {
      "description" : "United States Dollar",
      "displayName" : "United States Dollar",
      "id" : "usd",
      "name" : "USD",
      "organization" : {
        ...
      },
      "status" : "ACTIVE",
      "virtualCurrency" : false
    },
    "usage" : 43.6000
  } ],
  "totalRecords" : 2
}

You can also retrieve a developer's prepaid balance for a particular month and year. You do this by issuing a GET request to /organizations/{org_name}/developers/{developer_id}/prepaid-developer-balance, where {developer_id} is the identification of the developer. You specify the pertinent month and year as query parameters in the request. You can also specify the support currency as a query parameter. For example:

$ curl -H "Accept:application/json" -X GET \
GET "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/dev2@myorg/prepaid-developer-balance?month=september&year=2013" \
-u myname:mypass

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

{
  "developerBalance": [
    {
      "approxTaxRate": 0.2,
      "currentBalance": 886,
      "currentTotalBalance": 1000,
      "currentUsage": 114,
      "id": "7355c525-f4c9-4fa6-b710-0df1cfd8703c",
      "month": "SEPTEMBER",
      "previousBalance": 0,
      "supportedCurrency": {
        ...
      "id": "eur",
        ...
      },
      "tax": 19,
      "topups": 0,
      "usage": 95,
      "year": 2013
      }
    ],
  "totalRecords": 1
}

Prepaid balance configuration settings for the API

The following prepaid balance configuration options are exposed to the API:

Name Description Default Required?
amount

The amount applied to the prepaid balance (in the applicable currency).

N/A Yes
supportedCurrency

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

N/A Yes
txReference

The payment provider’s transaction reference.

N/A No

Get help

For help, see Apigee Customer Support.

Next steps

You can post refunds (for purchase transactions only) using monetization. Learn how in Post refunds.

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