Managing prepaid account balances

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

Note: The monetization features specified in the November 3 2021 Apigee Monetization release notes are supported only on Apigee.

This page describes how you can manage your prepaid billing accounts.

You can use the Apigee APIs to manage the prepaid billing accounts of your developers. By using the APIs, you can perform the following tasks:

• View monetization configuration
• Update monetization configuration
• View developer balance
• Credit developer balance
• Adjust developer balance

Note: Your rate plans determine how much money is deducted from the prepaid accounts. For information about configuring rate plans, see Managing rate plans for API products.

View monetization configuration

To view the monetization configuration of a developer, issue a GET request to the following API:

https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/developers/$DEVELOPER_EMAIL_ID/monetizationConfig

With this API, you can view the billing type of the developer. For more information about the API, see getMonetizationConfig.

The following example shows you how to view the monetization configuration for a developer by using the curl command:

curl -H "Authorization: Bearer $TOKEN" \
https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/developers/$DEVELOPER_EMAIL_ID/monetizationConfig

When you run the command, you can see a response similar to the following:

{
  "billingType": "PREPAID",
}

Update monetization configuration

To update the monetization configuration of a developer, issue a PUT request to the following API:

https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/developers/$DEVELOPER_EMAIL_ID/monetizationConfig

With this API, you can update the billing type of the developer. For more information about the API, see updateMonetizationConfig.

The following example shows you how to update the monetization configuration for a developer by using the curl command:

curl -H "Authorization: Bearer $TOKEN" \
-H "Content-type: application/json" \
-X PUT \
-d '{
"billingType": "POSTPAID",
}' \
https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/developers/$DEVELOPER_EMAIL_ID/monetizationConfig

When you run the command, you can see a response similar to the following:

{
  "billingType": "POSTPAID",
}

Change of billing type

Your developers can switch their billing from prepaid to postpaid and vice versa. This section describes the changes that happen in Apigee when developers change their billing type.

Postpaid to prepaid

If a developer switches from postpaid to prepaid, Apigee immediately sets the developer's billingType to PREPAID in the configuration. The developer can start using the APIs to the extent of the prepaid top-up amount. Based on your custom monetization reports, any existing usage in the developer's postpaid account should be billed separately by you (API provider).

Prepaid to postpaid

If a developer switches from prepaid to postpaid, Apigee immediately sets the developer's billingType to POSTPAID in the configuration. Your custom monetization reports show any existing balance (of all the currencies) in the developer's prepaid account as a credit transaction. When calculating the amount due from a developer after the billing cycle, you (API provider) must consider the credit balance in the developer's account.

View developer balance

To view the balance in a developer's prepaid account, issue a GET request to the following API:

https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/developers/$DEVELOPER_EMAIL_ID/balance

For more information about the API, see getBalance.

The following example shows you how to view the balance in a developer's prepaid account:

curl -H "Authorization: Bearer $TOKEN" \
https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/developers/$DEVELOPER_EMAIL_ID/balance

When you run the command, you can see a response similar to the following:

{
  "wallets": [
    {
      "balance": {
        "currencyCode": "USD",
        "units": "150",
        "nanos": 500000000
      },
      "lastCreditTime": 1234567890
    },
    {
      "balance": {
        "currencyCode": "INR",
        "units": "10000",
        "nanos": 600000000
      },
      "lastCreditTime": 9876543210
    }
  ]
}

In the sample response, the developer has two prepaid account balances; one for each currency. You can know the balance amount from the units and the nanos fields. The lastCreditTime field is in epoch time format, and denotes the time at which the developer's balance was last credited.

Negative developer balance

If a developer makes multiple API calls within a short time span, it is possible that the developer is allowed to make excess API calls, which results in a negative wallet balance for the developer.

This scenario occurs when multiple message processors are handling the API calls from the same developer. Every message processor will have a copy of the developer's balance based on which it allows the API calls. All message processors periodically sync their balances with the main balance in the Cassandra database. Because of the minor delays in syncing, the wallet balance of a developer in a message processor might be out of sync with the main balance. For example, at a given point in time, if the developer's wallet balance in a message processor is USD 2, the main balance might be USD 0. So the message processor allows the API calls from the developer, thinking that the developer's wallet still has USD 2.

Apigee syncs a message processor's wallet balance in near real time with minor delays, and you cannot control or configure this behavior of Apigee. However, all the excess API calls made by a developer are accounted for. After processing all the API calls of a developer, the final amount in the developer's wallet reflects the charge even for the excess API calls. So, when the developer recharges the account next time, to have a positive wallet balance, the developer must first pay up any negative balance amount in the wallet.

Credit developer balance

To credit the balance in a developer's prepaid account, issue a POST request to the following API:

https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/developers/$DEVELOPER_EMAIL_ID/balance:credit

For more information about the API, see creditBalance.

Crediting a developer's balance involves the following steps in order:

1. A developer tops-up the developer account from the developer portal by using a payment gateway.
2. The developer portal generates a unique transaction ID for the top-up.
3. The developer portal updates the developer balance by using the organizations/{org}/developers/{developer}/balance:credit API.

This following example shows the API call for step 3 and credits the developer's balance by USD 150.21. The transactionId is set to the value of the transaction ID of the top-up transaction (step 3).

curl -H "Authorization: Bearer $TOKEN" \
-H "Content-type: application/json" \
-X POST \
-d '{
  "transactionAmount": {
     "currencyCode": "USD",
     "units": "150",
     "nanos": 210000000
  },
  "transactionId": "ab31b63e-f8e8-11eb-9a03-0242ac130003"
}' \
https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/developers/$DEVELOPER_EMAIL_ID/balance:credit

When you run the command, you can see a response similar to the following:

{
  "wallets": [
    {
      "balance": {
        "currencyCode": "USD",
        "units": "300",
        "nanos": 710000000
      },
      "lastCreditTime": "9876543210"
    },
    {
      "balance": {
        "currencyCode": "INR",
        "units": "10000",
        "nanos": 600000000
      },
      "lastCreditTime": "1234567890"
    }
  ]
}

Note: After you credit a developer's balance for a currency, it takes about 5 minutes for the new balance to reflect in all of Apigee's components. During this time, if you again try to credit the developer's balance for the previously credited currency, the creditBalance API reports an error. Therefore, as a best practice, provide a gap of about 5 minutes between two credits of a particular currency.

Adjust developer balance

If you have under-charged or over-charged a developer's account, you can use the adjustBalance API to decrease or increase the account balance.

To adjust the balance in a developer's prepaid account, issue a POST request to the following API:

https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/developers/$DEVELOPER_EMAIL_ID/balance:adjust

For more information about the API, see adjustBalance.

If you want to decrease the balance of an under-charged developer, set the units field in the request to a positive value. The following example decreases the balance in a developer's prepaid account by USD 50:

curl -H "Authorization: Bearer $TOKEN" \
-H "Content-type: application/json" \
-X POST \
-d '{
  "adjustment": {
    "units": "50",
    "currencyCode": "USD"
  }
}' \
https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/developers/$DEVELOPER_EMAIL_ID/balance:adjust

When you run the command, you can see a response similar to the following:

{
  "wallets": [
    {
      "balance": {
        "currencyCode": "USD",
        "units": "150"
      },
      "lastCreditTime": "1635489199530"
    }
  ]
}

If you want to increase the balance of an over-charged developer, set the units field in the request to a negative value. The following example increases the balance in a developer's prepaid account by USD 50.1:

curl -H "Authorization: Bearer $TOKEN" \
-H "Content-type: application/json" \
-X POST \
-d '{
  "adjustment": {
    "units": "-50",
    "nanos": "100000000",
    "currencyCode": "USD"
  }
}' \
https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/developers/$DEVELOPER_EMAIL_ID/balance:adjust

When you run the command, you can see a response similar to the following:

{
  "wallets": [
    {
      "balance": {
        "currencyCode": "USD",
        "units": "200",
        "nanos": 100000000
      },
      "lastCreditTime": "1635489199530"
    }
  ]
}