Make billing adjustments

Introduction

Monetization allows you to make adjustments to billing details. For example, you might need to increase or decrease the revenue share or fees for a given billing month because of a discrepancy in your records.

Exploring the Billing Adjustments page

Access and explore the Billing Adjustments page using the New Edge UI and Classic Edge UI.

New Edge UI

To access the Billing Adjustments page:

  1. Sign in to apigee.com/edge.
  2. Select Publish > Monetization > Billing Adjustments in the left navigation bar.

The Billing Adjustments page is displayed.

As highlighted in the figure, the Billing Adjustments page enables you to:

Classic Edge UI

To access the Billing Adjustments page:

  1. Sign in to enterprise.apigee.com.
  2. Select Monetization > Adjustments in the top navigation bar.

The Billing Adjustments page enables you to:

  • View the current list of billing adjustments
  • Add a billing adjustment
  • Edit a billing adjustment
  • Search the list of billing adjustments

Add a billing adjustment

To add a billing adjustment:

  1. Access the Billing Adjustments page.
  2. Click + Adjustment.
  3. Enter the following information:
    Field Description
    Name

    A descriptive name that will appear on the billing document.

    Adjustment %

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

    Billing Month

    Billing month for the adjustment. Select a month from the drop-down list.

    Transaction Type

    Type of transaction for which you want to apply the adjustment. Select a value from the drop-down:

    • All Transactions
    • Charge (charging model transactions)
    • Purchase (revenue sharing model transactions)
    • Refund (revenue sharing model transactions)
    Product

    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.

    Developer

    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 Create adjustment.

Editing a billing adjustment

To edit a billing adjustment:

  1. Access the Billing Adjustments page.
  2. Position the cursor over the billing adjustment you want to edit and click in the actions menu.
  3. Update the billing adjustment, as required.
  4. Click Update Adjustment.

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 details by issuing a POST request to /organizations/{org_name}/billing-adjustments. When you make the request, you specify in the request body:

  • Name for the billing adjustment.
  • An adjustment percentage, that is, a positive or negative percentage value that respectively increases or reduces the bill.
  • Billing month.
  • Billing year.
  • Organization to which the billing adjustment is applied.

You can also specify other properties, such as:

  • Type of transaction for which you want to apply the adjustment (such as a purchase transaction).
  • Developer for whom you want to apply the adjustment.
  • Whether you want to apply the adjustment to prepaid developers, postpaid developers, or both.
  • API package for which you want to apply the adjustment.
  • 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"
}

Viewing billing adjustments using the API

You can view a specific billing adjustment or all billing adjustments for an organization. To view 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 view all the billing adjustments 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.