# Pricing API Overview

The **Pricing API** enables you to simulate billing outcomes for one or more products before creating or updating an account’s subscriptions. This is useful for generating quotes, estimating costs, and validating billing logic using existing rate and pricing configurations.

## Use Cases

- Quoting charges before committing account product changes
- Validating billing impact of product additions or updates
- Predicting subscription cycles, charges, and credits
- Simulating contract, rate class, and currency overrides


## How It Works

You send a request to the API with product details, optional account context, and configuration parameters. The API responds with a detailed breakdown of predicted charges, credits, subscription periods, and calculated totals.

## Request Format

The API request must provide key information related to the existing product(s) and related rating/account information.

| **Field** | **Type** | **Description** |
|  --- | --- | --- |
| `Products` | Array | List of products to quote |
| `ProductId` or `ProductObj` | Number / Object | Required unless `AccountProduct` is provided |
| `AccountId` or `AccountObj` | Number / Object | Optional; used to derive currency, billing cycle |
| `AccountProductId` or `AccountProductObj` | Number / Object | Optional; required when quoting updates to existing subscriptions |
| `ContractId` or `ContractObj` | Number / Object | Optional; defines pricing context when multiple contracts exist |
| `RateClassId` or `RateClassObj` | Number / Object | Optional; for quoting with a specific rate class |
| `Quantity` | Number | Required product quantity |
| `StartDate`, `RenewalStartDate`, `EndDate` | Date (YYYY-MM-DD) | Define the subscription’s timeline |
| `CurrencyCode` | Text | Optional if `Account` is provided |
| `RateOverride` | Number | Optional; overrides all rates in the calculation |
| `Attributes` | Object or Array | Optional for formula-based or filtered pricing logic |


You may use object lookups (`ProductObj`, `AccountObj`, etc.) instead of IDs if referencing external systems.

## Sample Request (JSON)


```json
{
  "Products": [
    {
      "ProductObj": { "Name": "Premium Hosting" },
      "AccountObj": { "Name": "Acme Corp" },
      "Quantity": 2,
      "StartDate": "2025-06-01",
      "EndDate": "2025-12-31",
      "CurrencyCode": "USD"
    }
  ]
}
```

## Response Format

The API returns predicted charges, credits, totals, and other details per product.

| **Field** | **Type** | **Description** |
|  --- | --- | --- |
| `Products` | Array | List of calculated results |
| `ProductId`, `ProductName` | Number, Text | Identifiers for the quoted product |
| `RatingMethodType` | Text | Rating method used |
| `FirstCycleCost`, `LastCycleCost`, `TotalCost` | Number | Cycle-based and total cost calculations |
| `Charges` | Array | Detailed charges per cycle |
| `Credits` | Array | Predicted credits |
| `Error` | Text | If any issues occurred during calculation |


## Sample Charge Output

| **Field** | **Description** |
|  --- | --- |
| `ActivityDate` | Date of the charge |
| `Quantity`, `Rate`, `Cost` | Billing details per cycle |
| `ContractId`, `RateClassId` | Context used for pricing |
| `SubscriptionStartDate`, `SubscriptionEndDate` | Calculated cycle dates |


## Billing Cycle Logic

The API supports the following billing cycle behaviors:

- **Start Date Syncing** – Charges start from the specified `StartDate`, optionally aligned with `RenewalStartDate`.
- **Account-Based Syncing** – If `Account` is provided, its billing cycle determines the charge periods.


> **Note:** The API does not support mismatched billing cycles (e.g., quoting an annual product for a predicted monthly account).


## Rate Resolution Priority

The system uses the following logic to determine applicable rates (in order of priority):

1. `RateOverride` (if provided)
2. Rates on the specified `AccountProduct`
3. Rates from `Contract` (or its `RateClass`)
4. Rates from explicitly provided `RateClass`
5. Default rate hierarchy on `Account` and its parents


## Limitations

- **Packages & Package Products**: Not supported in this version
- **Mismatched Billing Cycles**: Unsupported for predicted (non-existent) accounts