Use Case: Consumption-based Billing Workflow

The consumption based billing workflow starts with creating a usage input to capture the metered usage in the system. When rated, the system determines the applicable fee using the configured price tiers and rating method based on the reported quantity.

The rated usage inputs can be reversed by using the Unrating functionality. This gives an opportunity to correct the usage inputs (with quantity or submission date) before rating again so that the customer can be invoiced correctly for the billing period.

Conga Billing also allows the users to estimate or forecast the fee based on the Draft Quantity loaded.

Create a Usage Input

Call the Usages Input creation API (https://<URL of the Instance>/api/billing/v1/usage-inputs) and enter the following payload:

[
    {
        "Type": "Regular",
        "SubmissionDate": "2025-04-10T00:00:00",
        "SubscriptionIdentifierObject": "OrderLineItem",
        "SubscriptionIdentifierField": "Id",
        "SubscriptionIdentifierValue":
        "70aca2c7-e40e-48f7-bdf7-7f2d00c588d1",
        "UnitofMeasure": "Each",
        "Quantity": 650,
        "DraftQuantity": 5,
        "RatingStatus": "Loaded"

    }
]

The usage input is created in a Loaded status and the API returns the following response:

{
  "Summary": "string",
  "Results": [
    {
      "Id": "string",
      "RecordIndex": 0,
      "IsSuccess": true,
      "Errors": [
        "string"
      ]
    }
  ]
}

Rate a Usage Input

Rating is the process of converting a raw usage input (like a quantity consumed) into a monetary value, based on the pricing rules and tiers defined for the product or service. This is how the system determines how much to bill the customer for their usage.

Call the usage input rating API (https://<URL of the Instance>/api/billing/v1/usage-inputs/rate) and provide the following inputs:

{

  "ProcessAllUsageInputs": false, // if True, all usage input records with status as Loaded will be rated asynchronously.

  "UsageInputIds": [

        "{{UsageInputId1}}"

  ]

}

The API rates the usage input and returns the following response:

{
  "JobId": "string",
  "BatchResults": {
    "Summary": "string",
    "Results": [
      {
        "Id": "string",
        "RecordIndex": 0,
        "IsSuccess": true,
        "Errors": [
          "string"
        ]
      }
    ]
  },
  "IsSuccess": true,
  "Errors": [
    "string"
  ]
}

After successful processing, the status of the usage input changes to "Rated". The system rolls up this amount to schedule records and subsequently to the billing header.

Following methods are used to Rate a usage input:

Rate based on quantity's price (for Dimension Value = Discrete)
Rate based on quantity's exact tier price (for Dimension Value = Range)
Rate based on fee per tier from the starting tier (for Dimension Value = Cumulative Range)

Rate based on quantity's price (for Dimension Value = Discrete): In this method, each specific quantity (or combination of dimensions) has its own unique price. There is no range or cumulative calculation — only the exact quantities defined in the price matrix are rated. If a usage input matches a defined discrete quantity, the system picks up the corresponding price (Adjustment Amount) and uses it as the Rated Amount. If there's no exact match, the input is errored out and is not rated.

Suppose you have a product with the following discrete pricing:


Quantity	Adjustment Amount	Adjustment Type
10	USD 120.00	Tier Price
20	USD 150.00	Tier Price
30	USD 275.00	Tier Price
40	USD 500.00	Tier Price

If the entered quantity is 10, the Rated Amount will be USD 120.00, for 20 quantity the Rated Amount will be USD 150.00 and so on.

If the entered quantity is not defined (e.g., 15), the system will error out the usage input and will not rate it.

Rate based on quantity's exact tier price (for Dimension Value = Range): In this method of rating, the system checks the quantity entered for a usage input and determines which price tier (or slab) it falls into. The Rated Amount is calculated based on the price defined for that tier.

Suppose you have these tiers having both unit price and flat price:


Sequence	From	To	Adjustment Amount	Adjustment Type
1	1	100	USD 1,000.00	Tier Price
2	101	500	USD 9.00	List Price Override
3	501	2000	USD 8.00	List Price Override
4	2001	9999999 Note: It represents infinite consumption.	USD 7.00	List Price Override

If you enter a quantity of 50, the Rated Amount is USD 1,000.00 (falls in the first tier).
If you enter a quantity of 150, the Rated Amount is 150 * 9 = USD 1,350.00 (falls in the second tier) and so on.

Rate based on fee per tier from the starting tier (for Dimension Value = Cumulative Range):

This method calculates the rated amount by summing up the charges for each tier up to the total usage quantity, that is, it adds up the charges for all tiers up to the entered quantity, not just the tier where the quantity falls.
Each tier has its own price or adjustment, and the system accumulates the charges as the quantity crosses each tier boundary.

Considering the above table, if the entered quantity is 650, the rated amount calculation will be:

For first 100 quantity: USD 1,000.00.
For next 400 quantity: 400 * 9 = USD 3,600.00.
For next 150 quantity: 150 * 8 = USD 1,200.00.
Rated Amount = USD 1,000.00 + USD 3,600.00 + USD 1,200.00 = USD 5,800.00.

Get the Usage Input Details

Call the Get Usage Inputs API (https://<URL of the Instance>/api/billing/v1/usage-inputs/{{UsageInputId1}}). The API returns following response with the usage input details:

{
    "Id": "5a865f66-40a6-4349-8756-bf83d9ee9073",
    "Name": "UI-000000411",
    "CreatedBy": {
        "Id": "2895942d-f5ec-0e20-b84f-63f9a1661d58",
        "Name": "Billings User 02"
    },
    "CreatedDate": "2026-04-21T16:10:33.403",
    "ModifiedBy": {
        "Id": "2895942d-f5ec-0e20-b84f-63f9a1661d58",
        "Name": "Billings User 02"
    },
    "ModifiedDate": "2026-04-21T16:10:43.292",
    "ExternalId": null,
    "ETag": "747389cf-397e-4598-a754-0f053187d15c",
    "Type": "Regular",
    "SubscriptionIdentifierObject": "OrderLineItem",
    "SubscriptionIdentifierField": "Id",
    "SubscriptionIdentifierValue": "70aca2c7-e40e-48f7-bdf7-7f2d00c588d1",
    "SubscriptionIdentifierRecordID": "70aca2c7-e40e-48f7-bdf7-7f2d00c588d1",
    "UnitofMeasure": "Each",
    "Quantity": 650.00000,
    "RatedAmount": {
        "Value": 5800.0000000000,
        "DisplayValue": 5800.0000000000,
        "CurrencyCode": "EUR",
        "CurrencySymbol": "€"
    },
    "DraftQuantity": 5.00000,
    "DraftRatedAmount": null,
    "RatingStatus": "Rated",
    "BillingScheduleRecord": {
        "Id": "2a852abd-ae4e-4fb1-80f7-a368c3a67cc0",
        "Name": "BSR-000012631"
    },
    "UsageInputNumber": "UI-000000411",
    "Currency": "EUR",
    "BillingHeader": {
        "Id": "c25a77a0-542e-4f57-b21e-b2e0e406deba",
        "Name": "BH-000001195"
    },
    "PeriodStartDate": null,
    "PeriodEndDate": null,
    "SubmissionDate": "2025-04-10T00:00:00",
    "RatingMessage": "Usage Input has been successfully rated."
}

The Rated Amount of USD 5,800.00 is rolled up to the billing schedule record (BSR).

Note: Multiple usage inputs can be rated in a similar way and the rated amount is rolled up to the respective BSRs.

Estimate a Usage Input

Estimating is a forecasting step where the API calculate a draft billable amount for a usage input before actually rating it. This is useful for revenue forecasting and also for alerting the customers about the incurred draft bill based on the consumption so far..

Call the Estimate Usage Inputs API (https://<URL of the Instance>/api/billing/v1/usage-inputs/estimate) and provide the following input.

{
  "UsageInputIds": [
    "string"
  ],
  "ProcessAllUsageInputs": false, // if True, all usage input records with status as Loaded will be estimated asynchronously. 
}

The API returns the following response.

{
  "JobId": "string",
  "BatchResults": {
    "Summary": "string",
    "Results": [
      {
        "Id": "string",
        "RecordIndex": 0,
        "IsSuccess": true,
        "Errors": [
          "string"
        ]
      }
    ]
  },
  "IsSuccess": true,
  "Errors": [
    "string"
  ]
}

The usage input's status remains Loaded (not Rated), and the draft amount is shown in the Draft Rated Amount field. This amount is not rolled up to the BSR and is not used for invoicing.

Unrate a Usage Input

Unrating a usage input is the process of reversing or rolling back a previously rated usage input. When you unrate a usage input, you are essentially telling the system to undo the billing calculation that was derived while rating the usage input. After successful operation, the usage input's status changes from Rated to Unrated. The Rated Amount on the usage input is set to null (not zero), meaning the system no longer considers this input for billing and the Consumed Quantity and Rated Amount will be reduced on the corresponding BSR. On the billing header, the Pending Invoice Amount field is updated to the latest value.

Call the Unrate usage inputs API (https://<URL of the Instance>/api/billing/v1/usage-inputs/unrate) and provide the following input.

{
  "UsageInputIds": [  
    "string"                 // id of the usage input to be unrated
  ]
}

The API returns the following response.

{
  "Summary": "string",
  "Results": [
    {
      "Id": "string",
      "RecordIndex": 0,
      "IsSuccess": true,
      "Errors": [
        "string"
      ]
    }
  ]
}

Conga Product Documentation

Welcome to the new doc site. Some of your old bookmarks will no longer work. Please use the search bar to find your desired topic.