Make billing adjustments

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.

Making billing adjustments using the UI

The following sections describe how to make billing adjustments using the UI.

Making a billing adjustment

To make a billing adjustment:

  1. On the Monetization tab, select Adjustments.

    This opens the Adjustments page.

  2. Click +Post Adjustment.

    This opens the Post Adjustment page.

  3. Enter the following information:
    Field Description
    Billing Month

    The billing month for the adjustment. Select a month from the drop-down list. Only "open" months are listed. 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.

    Name

    A descriptive name that will appear on the billing document.

    Adjustment

    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. Enter a positive or negative decimal number (with up to two decimal places).

    Package

    The API package for which you want to apply the adjustment. 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. Select an API package from the drop-down menu.

    API Product

    The API product for which you want to apply the adjustment. 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. Select an API product from the drop-down menu.

    Transaction Type

    The type of transaction for which you want to apply the adjustment. You can apply the adjustment to all transactions (by default) or to a specific transaction. Select "All transactions" or a specific transaction type from the drop-down menu. The specific transaction types are:

    • Charge (for charging model transactions).
    • Purchase (for revenue sharing model transactions).
    • Refund (for revenue sharing model transactions).
    Developer

    The developer for whom you want to apply the adjustment. You can apply the adjustment to all developers (by default) or to a specific developer. Select "All Developers" or a specific developer from the drop-down menu.

  4. Click Save to save the adjustment (or Cancel to cancel).

Viewing and editing adjustments

You can view both open adjustments and closed adjustments. An open adjustment is an adjustment that has not yet been applied in published billing documents. A closed adjustment is an adjustment that has been applied in published billing documents.

To view adjustments:

  1. On the Adjustments page, select a billing month from the drop-down list.
  2. Click Open Adjustments to view the open adjustments, or Closed Adjustment to view the closed adjustments.

To edit an open adjustment:

  1. Click Edit in the Action column for the applicable adjustment.

    This opens an Edit Adjustment page.

  2. Update the adjustment, as needed. You can change the name and adjustment percentage. However, you cannot change the initial API Package, API Product, Transaction Type, or Developer selections. You can remove an adjustment, by making the adjustment percentage 0.
  3. Click Save to save the adjustment edits (or Cancel to cancel).

Making billing adjustments using the API

The following sections describe how to make billing adjustments using the API.

Making a billing adjustment using the API

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 product 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": 2017,
  "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 email:password

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

{
  "adjustmentPercentageFactor" : -3,
  "billingMonth" : 6,
  "billingYear" : 2017,
  "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 using the API

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 email:password

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 email:password

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

{
  "billingAdjustment" : [ {
    "adjustmentPercentageFactor" : -3,
    "billingMonth" : 6,
    "billingYear" : 2017,
    "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" : 2017,
    "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 using the API

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": 2017,
  "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 email:password

Deleting a billing adjustment using the API

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 email:password

Billing adjustment configuration settings for the API

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 numeric percentage. A positive percentage adjusts up the revenue share or fees in the transaction by that percentage. A negative percentage adjusts down the revenue share or fees in the transaction by that percentage. Values can range from -100 to 999.9999.

N/A Yes
billingMonth

The billing month for the billing adjustment, specified as an integer. For example, 11 for December.

N/A Yes
billingYear

The billing year for the billing adjustment, specified using the following format: YYYY. For example, 2017.

N/A Yes
organization

The organization to which the billing adjustment applies.

N/A Yes
isPublished

A flag that specifies whether the adjustment should be published 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
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.

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.

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.

N/A No

Next steps

Monetization gives you the flexibility to issue credits to a developer. You might need to do this if a developer is unsatisfied with a service and requests a partial or full refund on usage for a period. Learn how to issue credit in Issuing credits.