You're viewing **Apigee Edge** documentation. [Go to the **Apigee X** documentation](http://cloud.google.com/apigee/docs/reference/apis/apigee/rest/v1/organizations.developers.balance/adjust). 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. ### Edge To access the Billing Adjustments page using the Edge UI: 1. Sign in to [apigee.com/edge](https://apigee.com/edge). 2. Select **Publish \> Monetization \> Billing Adjustments** in the left navigation bar. The Billing Adjustments page is displayed. ![](https://docs.apigee.com/static/api-platform/images/billing-adjustments.png) As highlighted in the figure, the Billing Adjustments page enables you to: - View the current list of billing adjustments - [Add a billing adjustment](https://docs.apigee.com/api-platform/monetization/make-billing-adjustments#add) - [Edit a billing adjustment](https://docs.apigee.com/api-platform/monetization/make-billing-adjustments#edit) - Search the list of billing adjustments ### Classic Edge (Private Cloud) > [!NOTE] > **Note:** The Classic Edge UI is available with Edge for Private Cloud only. To access the Billing Adjustments page using the Classic Edge UI: 1. Sign in to `http://ms-ip:9000`, where ms-ip is the IP address or DNS name of the Management Server node. 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 > [!NOTE] > **Note:** The steps in the topics that follow are specific to the Edge UI. The Classic Edge UI steps are similar to those described. ## Add a billing adjustment To add a billing adjustment: 1. [Access the Billing Adjustments page](https://docs.apigee.com/api-platform/monetization/make-billing-adjustments#ui). 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. > [!NOTE] > **Note:** Any adjustment that you make for a specific developer overrides adjustments made across all developers. | 4. Click **Create adjustment**. ## Editing a billing adjustment To edit a billing adjustment: 1. [Access the Billing Adjustments page](https://docs.apigee.com/api-platform/monetization/make-billing-adjustments#ui). 2. Position the cursor over the billing adjustment you want to edit and click ![](https://docs.apigee.com/static/api-platform/images/edit-icon.png) 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](https://docs.apigee.com/api-platform/monetization/make-billing-adjustments#billadjops) 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. > [!NOTE] > **Note:** 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. > [!NOTE] > **Note:** 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. > [!NOTE] > **Note:** Any adjustment that you make for a specific developer always overrides any adjustments made for 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](https://docs.apigee.com/api-platform/monetization/manage-credit).