Introduction

Monetization gives you the flexibility to issue developer credit. For a postpaid developer, a credit appears as a separate line in an invoice, reducing the charge in an invoice.

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

Once you issue a credit to a developer, you cannot change it directly. However, you can effectively change or remove the credit by creating a credit with a negative amount for the same developer.

You can also set a credit limit for postpaid developers. This means that you can issue credit to applicable postpaid developers up to the credit limit.

Toolbox

You can issue credit using the management UI or monetization API.

If you use the UI, you issue credit on the Credits page.

If you use the API, you can apply credit against a package as a whole, or against the use of a specific product within a package. You apply a credit against a package by issuing a POST request to the /organizations/{org_name}/monetization-packages/{package_id}/rate-plans/{rate-plan_id}/real-currency-credit-transactions resource. Optionally, you can identify as a query parameter an API product to which the credit applies.

Using the API, you can set a credit limit for a postpaid developer by issuing a POST request to /organizations/{org_name}/developers/{developer_id}/developer-credit-limit.

Issuing credit using the UI

The month in which the credit applies. Select either Current Month or Previous month.

Developer

The developer to whom the credit applies. Select a developer from the drop-down menu.

Package

The API package for which the credit applies. Select an API package from the drop-down menu.

Product

The API product in the selected API package for which the credit applies. Select an API package from the drop-down menu. You can select All Products in the package or a specific product.

Currency

The currency used for the credit. This is the currency that was set up for the plan in the package that the developer purchased (it cannot be changed). If there are multiple currencies in a plan, you can select from one of the currencies.

Issuing credit using the API

You can issue credit to a developer. You can apply credit against a package as a whole, or against the use of a specific product within a package.

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

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

The identification of the developer to whom the credit applies.

The amount of the credit.

The currency used for the credit.

A note describing the reason for the credit.

The billing month to which the credit applies.

The billing year to which the credit applies.

Optionally, you can identify as a query parameter an API product to which the credit applies. If you don’t specify a product ID, the credit applies to all products in the API package.

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

Setting a credit limit using the API

When you add a supported currency for an organization, you can set a credit limit (see Adding supported currencies). The credit limit applies to all postpaid developers in the organization. This means that you can issue credit to the postpaid developers in the organization up to that limit. However, you can also set a credit limit for an individual postpaid developer. If you do that, the limit overrides any supported currency limit, but only for that developer.

To set a credit limit for an individual developer, issue a POST request to /organizations/{org_name}/developers/{developer_id}/developer-credit-limit, where {developer_id} is the identification of the developer. When you issue the request, you need to specify as query parameters the amount of the credit and the currency used for the credit. For example, the following request sets a credit limit of $1000 for a developer:

Retrieving a credit limit using the API

To retrieve a credit limit for a postpaid developer issue a GET request to /organizations/{org_name}/developers/{developer_id}/developer-credit-limit, where {developer_id} is the identification of the developer. For example: