Was this Helpful?

Introduction

As part of its initial setup of  monetization, the Apigee Edge configuration team specifies currencies supported by your organization (including currencies supported by sub-organizations if your organization is a group organization). It also specifies the default currency for your organization.

You can retrieve the currencies that your organization supports, add supported currencies, or delete supported currencies (if the currencies are not used by a developer or a rate plan).

Monetization automatically runs a daily job that obtains the exchange rate in U.S. dollars for each supported currency. By default, the job runs every day at 1 second past midnght. You can change the schedule for the job or disable it. For details, see Schedule monetization jobs.

Toolbox

You can manage supported currencies using the management UI or monetization API. If you use the UI, you manage the supported currencies in the Tax and Currency section of the Organization Profile page.

If you use the API, you add supported currencies by issuing a POST request to the /organizations/{org_name}/supported-currencies resource. You retrieve, update, and delete a supported currency by making GET, PUT, and DELETE requests, respectively to the /organizations/{org_name}/supported-currencies/{currency_id} resource.

You can also change the default currency for the organization. Using the UI, you can set the default currency in the Tax and Currency section of the Organization Profile page. Using the API, you update the organization profile (see Updating the organization profile using the API for details). In the update, set the currency property to the name (that is, the ISO 4217 currency code) of the supported currency that you want to make the default.

Managing supported currencies using the UI

You manage supported currencies in the Tax and Currency section of the Organization Profile page. See Editing the organization profile in the UI for details.

Retrieving supported currencies using the API

You can retrieve an individual currency supported by your organization or all the currencies supported by your organization, including the currencies supported by its sub-organizations (if your organization is a group organization). You can also retrieve the currencies supported by a specific sub-organization, including the currencies supported by its parent organization.

To retrieve an individual currency supported by your organization, issue a GET request to /organizations/{org_name}/supported-currencies/{supportedCurrencyId}, where {supportedCurrency_id} is the identification of the supported currency to be retrieved. For example:

$ curl -X GET -H "Accept: application/json"  \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/supported-currencies/usd" \
-u myname:mypass

To retrieve all the currencies supported by your organization, issue a GET request to /organizations/{org_name}/supported-currencies. For example:

$ curl -X GET -H "Accept: application/json"  \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/supported-currencies" \
-u myname:mypass

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

{
"supportedCurrency" : [ {
    "description" : "US Dollar",
    "displayName" : "US Dollar",
    "id" : "usd",
    "name" : "USD",
    "organization" : {
      ...
    "status" : "ACTIVE",
    "virtualCurrency" : false
  }, {
    "creditLimit" : 5000.0000,
    "description" : "Euro",
    "displayName" : "Euro",
    "id" : "eur",
    "name" : "EUR",
    "organization" : {
      ...
    },
    "status" : "INACTIVE",
    "virtualCurrency" : false  
  } ],
  "totalRecords" : 2
}

If you organization is a group organization, you can retrieve its supported currencies as well as the currencies supported by its sub-organizations by issuing a GET request to /organizations/{org_name}/supported-currencies and specifying includeChildren=true as a query parameter. For example:

$ curl -X GET -H "Accept: application/json"  \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/supported-currencies?includeChildren=true" \
-u myname:mypass

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

{
  "supportedCurrency" : [ {
    "description" : "Colombia Pesos",
    "displayName" : "Colombia Pesos",
    "id" : "cop",
    "name" : "COP",
    "organization" : {
      ...
    },
    "status" : "ACTIVE",
    "virtualCurrency" : false
  }, {
    "description" : "El Salvador Colones",
    "displayName" : "El Salvador Colones",
    "id" : "svc",
    "name" : "SVC",
    "organization" : {
     ...
    },
    "status" : "ACTIVE",
    "virtualCurrency" : false
  }, {
    "description" : "Bolivia Bolivianos",
    "displayName" : "Bolivia Bolivianos",
    "id" : "bob",
    "name" : "BOB",
    "organization" : {
     ...
    },
    "status" : "ACTIVE",
    "virtualCurrency" : false
  }, 
  ...
  } ]
}

To retrieve the supported currencies for a sub-organization and its parent organization, issue a GET request to /organizations/{suborg_name}/supported-currencies, where {suborg_name} is the identification of the sub-organization. Specify includeParent=true as a query parameter. For example:

$ curl -X GET -H "Accept: application/json"  \
"https://api.enterprise.apigee.com/v1/mint/organizations/{suborg_name}/supported-currencies?includeParent=true" \
-u myname:mypass

Adding supported currencies using the API

You add supported currencies by issuing a POST request to /organizations/{org_name}/supported-currencies. For each supported currency you add, you need to specify the following in the request body:

  • The name of the supported currency. The name is the ISO 4217 code for the currency, such as USD for Unites States dollar.
  • A display name.
  • A description.
  • Whether or not the currency is virtual currency.
  • The status of the currency, that is, whether or not the currency is available for use.
  • The organization for which  the supported currency will be added.

You can also set a credit limit for a supported currency. This applies only to postpaid developers.

See Supported currency configuration settings for further details about these options.

For example, the following adds a supported currency for an organization:

$ curl -H "Content-Type: application/json" -X POST -d \
'{
   "description": "US Dollar",
   "displayName": "US Dollar",
   "virtualCurrency": "false",
   "name": "USD",
   "organization": {
   "id": "{org_name}"
   },
   "status": "ACTIVE"
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/supported-currencies" \
-u myname:mypass

If your organization is a group organization, any supported currency that you add to a sub-organization is also added to the parent organization (if that currency is not already supported by the parent organization).

Updating a supported currency using the API

You can update a supported currency by issuing a PUT request to /organizations/{org_name}/{supportedCurrencyId}, where {supportedCurrency_id} is the identification of the supported currency to be updated. When you make the update, you need to specify in the request body the updated properties as well as the identification of the supported currency. For example, the following API call updates the description and display name for a supported currency (the updated properties are highlighted in the example):

$ curl -H "Content-Type: application/json" -X PUT -d \
'{
   "description": "United States Dollar",
   "displayName": "United States Dollar",
   "id": "usd",
   "name": "USD",
   "organization": {
     "id": "{org_name}"
   },
   "status" : "ACTIVE",
   "virtualCurrency": "false"
}' \
"https://api.enterprise.apigee.com/v1/mint/organization/{org_name}/supported-currencies/usd" -d \
-u myname:mypass

Deleting a supported currency using the API

To delete a supported currency, issue a DELETE request to /organizations/{org_name}/supported-currencies/{currency_id}, where {currency_id} is the identification of the supported currency to be deleted. For example:

$ curl -X DELETE -H "Accept: application/json"  \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/supported-currencies/usd" \
-u myname:mypass

If your organization is a group organization, any supported currency that you delete from a sub-organization is automatically removed from the currencies supported by the parent organization — unless the currency is used by a developer or in a rate plan. If you try to delete a supported currency that is used by a developer or rate plan, you will get an error.

Supported currency configuration settings

The following supported currencies configuration options are exposed to the API:

Name Description Default Required?
name

The ISO 4217 code for the currency, such as USD for United States dollar.

N/A Yes
displayName

The name to display for the supported currency.

N/A Yes
description

A description of the supported currency.

N/A Yes
virtualCurrency

Indicates whether the supported currency is virtual currency. The value can be one of the following:

  • true. The supported currency is virtual currency.
  • false. The supported currency is not virtual currency.
N/A Yes
status

The status of the supported currency. The value can be one of the following:

  • ACTIVE. The supported currency is available for use.
  • INACTIVE. The supported currency is not available for use.
N/A Yes
creditLimit

This property applies only to postpaid developers. The credit limit for the supported currency.

The credit limit can be overridden for a developer in the developer's postpaid balance.

N/A No
organization

The organization for the supported currency.

N/A No

Get help

For help, see Apigee Customer Support.

Next steps

Learn how to set up bank accounts for your organization in Add bank accounts. You only need to set up bank accounts if you plan to support postpaid developers, and you want monetization to generate billing documents.

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