Was this helpful?

Introduction

Monetization allows you to make adjustments to billing documents. For example, you might need to increase or decrease the revenue share or fees specified in a billing document because of a discrepancy in your records.

You can make adjustments to billing documents only for "open" billing months. These are complete calendar months for which you have not yet published the billing documents. After you publish billing documents for a month, that month is "closed". You cannot make an adjustment for a closed month.

Toolbox

You can make billing adjustments using the monetization API.

Using the API, you make billing adjustments by issuing a POST request to the /organizations/{org_name}/billing-adjustments resource.

Making a billing adjustment

You can adjust billing documents by issuing a POST request to /organizations/{org_name}/billing-adjustments. When you make the request, you specify in the request body:

  • A name for the billing adjustment.
  • An adjustment percentage, that is, a positive or negative percentage value that respectively increases or reduces the bill in the billing documents.
  • The billing month (the billiing month must be an open billing month).
  • The billing year.
  • The organization to which the billing adjustment is applied.

You can also specify other properties, such as:

  • The type of transaction for which you want to apply the adjustment (such as a purchase transaction).
  • The developer for whom you want to apply the adjustment.
  • Whether you want to apply the adjustment to prepaid developers, postpaid developers, or both.
  • The API package for which you want to apply the adjustment.
  • The API package for which you want to apply the adjustment.

See Billing adjustment configuration settings for a complete list of billing adjustment properties that you can specify in an adjustment request.

If an optional property is not specified, the billing document adjustment will be all inclusive for that property. For example, if no transaction type is specified, the billing adjustment will apply to all transaction types.

The following example makes a billing adjustment for the open billing month, June, 2013. The adjustment makes a reduction by a factor of 3%, and is applied to purchase transactions, the payment product, and postpaid developers. Because the properties for identifying a specific developer or API package are not specified, the adjustment will be applied to all developers (who are postpaid developers), and the payment product in all API packages.

$ curl -H "Content-Type:application/json" -X POST -d \
'{
  "name": "Purchase Adjustment Negative3",
  "adjustmentPercentageFactor": "-3",
  "billingMonth": "6",
  "billingYear": "2013",
  "isPublished": "false",
  "transactionType": "PURCHASE",
  "developerBillingType": "POSTPAID",
  "organization": {
      "id": "{org_name}" 
  },
  "product": { "id": "payment" }
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/billing-adjustments" \
-u myname:mypass

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

{
  "adjustmentPercentageFactor" : -3,
  "billingMonth" : 6,
  "billingYear" : 2013,
  "developerBillingType" : "POSTPAID",
  "id" : "511144db-7fb1-4c74-bafb-5bc7a6380c9c",
  "isPublished" : false,
  "name" : "Purchase Adjustment Negative3",
  "organization" : {
   ...
  },
  "product" : {
    "customAtt1Name" : "user",
    "description" : "Payment",
    "displayName" : "Payment",
    "id" : "payment",
    "name" : "payment",
    "organization" : {
      ...
    },
    "status" : "CREATED",
    "transactionSuccessCriteria" : "Status=='200 OK'"
  },
  "transactionType" : "PURCHASE"
}

Retrieving billing adjustments

You can retrieve a specific billing adjustment or all billing adjustments for an organization. To retrieve a specific billing adjustment, issue a GET request to /organizations/{org_name}/billing-adjustments/{billing_adjustment_id}, where {billing_adjustment_id} is the identification of the specific billing adjustment (the ID is returned in the response when you create the billing adjustment). For example:

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/billing-adjustments/511144db-7fb1-4c74-bafb-5bc7a6380c9c" \
-u myname:mypass

To retrieve all the billing documents for an organization, issue a GET request to /organizations/{org_name}/billing-adjustments. For example:

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

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

{
  "billingAdjustment" : [ {
    "adjustmentPercentageFactor" : -3,
    "billingMonth" : 6,
    "billingYear" : 2013,
    "developerBillingType" : "POSTPAID",
    "id" : "511144db-7fb1-4c74-bafb-5bc7a6380c9c",
    "isPublished" : false,
    "name" : "Purchase Adjustment Negative3",
    "organization" : {
      ...
    },
    "product" : {
      "customAtt1Name" : "user",
      "description" : "Payment",
      "displayName" : "Payment",
      "id" : "payment",
      "name" : "payment",
      "organization" : {
        ...
      },
      "status" : "CREATED",
      "transactionSuccessCriteria" : "Status=='200 OK'"
    },
    "transactionType" : "PURCHASE"
  }, {
    "adjustmentPercentageFactor" : 5.0000,
    "billingMonth" : 5,
    "billingYear" : 2013,
    "id" : "53c363c0-7e1d-4dc1-9392-cf86656225f2",
    "isPublished" : false,
    "monetizationPackage" : {
      "description" : "Communications",
      "displayName" : "Communications",
      "id" : "communications",
      "name" : "Communications",
      "organization" : {
       ...
      },
      "product" : [ {
        "customAtt1Name" : "user",
        "description" : "Messaging",
        "displayName" : "Messaging",
        "id" : "messaging",
        "name" : "messaging",
        "organization" : {
          ...
        },
        "status" : "CREATED"
      }, {
        ...
        },
        "status" : "CREATED",
        "transactionSuccessCriteria" : "Status=='200 OK'"
      } ],
      "status" : "CREATED"
    },
    "name" : "Test Package Adjustment",
    "organization" : {
     ...
    },
    "product" : {
      "customAtt1Name" : "user",
      "description" : "Location",
      "displayName" : "Location",
      "id" : "location",
      "name" : "location",
      "organization" : {
        ...
      },
      "status" : "CREATED",
      "transactionSuccessCriteria" : "Status=='200 OK'"
    }
  } ],
  "totalRecords" : 2
}

Updating a billing adjustment

You can update a billing adjustment by issuing a PUT request to /organizations/{org_name}/billing-adjustments/{billing_adjustment_id}, where {billing_adjustment_id} is the identification of the specific billing adjustment. When you make the update, you need to specify in the request body the updated properties and the identification of the billing adjustment to be updated. You also need specify the mandatory properties for the billing adjustment, that is, properties for the name, adjustment percentage, billing month, billing year, and organization.

For example, the following API call updates the adjustment percentage factor and name (the updated properties are highlighted in the example):

$ curl -H "Content-Type: application/json" -X PUT -d \
'{
  "id" : "511144db-7fb1-4c74-bafb-5bc7a6380c9c ",
  "adjustmentPercentageFactor": "-5",
  "name" : "Purchase Adjustment Negative5",
  "billingMonth": "6",
  "billingYear": "2013",
  "isPublished": "false",
  "transactionType": "PURCHASE",
  "developerBillingType": "POSTPAID",
  "organization": {
      "id": "{org_name}" 
    },
  "product": { "id": "payment" }
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/billing-adjustments/511144db-7fb1-4c74-bafb-5bc7a6380c9c" \
-u myname:mypass

Deleting a billing adjustment

You can delete a billing adjustment by issuing a DELETE request to /organizations/{org_name}/billing-adjustments/{billing_adjustment_id}, where {billing_adjustment_id} is the identification of the billing adjustment to be deleted. For example:

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/billing-adjustments/511144db-7fb1-4c74-bafb-5bc7a6380c9c" \
-u myname:mypass

Billing adjustment configuration settings

The following configuration options are available for billing adjustments:

Name Description Default Required?
name

A descriptive name for the billing adjustment.

N/A Yes
adjustmentPercentageFactor

The amount of the adjustment, as a positive or negative percentage. A positive percentage adjusts up the revenue share or fees in the transaction by that percentage. A negative adjustment adjusts down the revenue share or fees in the transaction by that percentage.

N/A Yes
billingMonth

The billing month for the billing adjustment, such as JULY.

N/A Yes
billingMonth

The billing year for the billing adjustment, such as 2013.

N/A Yes
organization

The organization to which the billing adjustment applies.

N/A Yes
isPublished

Whether the adjustment should be The value can be one of the following:

  • true. The billing adjustment should be published.
  • false. The billing adjustment should not be published.

 

N/A No
transactionType

The type of transactions for which the billing adjustment applies. The type can be one of the following:

  • PURCHASE
  • CHARGE
  • REFUND
  • CREDIT
  • BALANCE
  • SETUPFEES
  • TERMINATIONFEES
  • RECURRINGFEES
  • TRUEUPS. These are transactions that are used to readjust rated transactions. They are invoked when tax changes are made in the previous billing month.

 

N/A No
developerBillingType

The developer billing type for which the billing adjustment applies. The value can be one of the following:

  • PREPAID.. Prepaid developers.
  • POSTPAID. Postpaid developers.
  • BOTH. Prepaid and postpaid developers.

 

N/A No
suborganization

The subsidiary or sub-organization to which the billing adjustment applies.

N/A No
product

The API product for which the billing adjustment applies. If you don’t specify this property, the billing adjustment applies to all API products.

You cannot apply a single adjustment to multiple API products. If you need to apply an adjustment to multiple API products, create an adjustment for each product.

N/A No
monetizationPackage

The API package for which the billing adjustment applies. If you don’t specify this property, the billing adjustment applies to all API packages.

You cannot apply a single adjustment to multiple API packages. If you need to apply an adjustment to multiple API packages, create an adjustment for each package.

N/A No
developer

The developer for whom the billing adjustment applies. If you don’t specify this property, the billing adjustment applies to all developers.

Any adjustment that you make for a specific developer always overrides any adjustments made for all developers.

N/A No

Get help

For help, see Apigee Customer Support.

Next steps

Monetization allows you to make adjustments to the traffic details recorded by API Services for your API products. Adjustments may be necessary for a variety of reasons, for example, due to discrepancies with your own records. Make adjustments to traffic details shows you how to how to make those adjustments.

Add new comment

Provide your email address if you wish to be contacted offline about your comment.
We will not display your email address as part of your comment.

We'd love your feedback and perspective! Please be as specific as possible.
Type the characters you see in this picture. (verify using audio)

Type the characters you see in the picture above; if you can't read them, submit the form and a new image will be generated. Not case sensitive.