Make billing adjustments

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

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 the Billing Adjustments page, as described below.

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.